@aiaiai-pt/design-system 0.8.4 → 0.9.0

package/components/VotingWidget.svelte

@@ -0,0 +1,292 @@
+<!--
+  @component VotingWidget
+
+  Participation vote panel — the Valongo V10 participation-grid primitive
+  (participatory budget, consultations, local polls). One question, a radio
+  group of options, a submit path, and a pseudonymised receipt after voting.
+  Presentational: it emits `onsubmit(optionId)`; the portal wires that to the
+  BFF public submit surface (`POST /{app}/public/submit`, voting placement —
+  #70 M4), and renders the bot-protection challenge into the `captcha` slot.
+
+  States (mutually exclusive vote-ability):
+   - open        — radio group + submit (the default)
+   - submitted   — confirmation + the `receipt` slot, voting locked
+   - closed      — voting period over; results only
+   - disabled    — not eligible (e.g. anonymous where login is required);
+                   options shown read-only with an announced `disabledReason`
+  Pass `showResults` to render the tally as labelled bars (typically once
+  `closed` or `submitted`).
+
+  Accessibility:
+   - `<fieldset>` + `<legend>` (the question) groups the options as a native
+     radio group — arrow-key navigation and "n of m" come for free.
+   - Submit is disabled until an option is chosen; the confirmation + receipt
+     land in an `aria-live="polite"` region so a screen reader announces them.
+   - Result bars are `aria-hidden`; each option's percentage is in its visible
+     text, so the meaning isn't colour/width-only.
+   - Radios keep a visible focus ring; reduced-motion disables the bar fill.
+
+  @example
+  <VotingWidget
+    question="Which project should Valongo fund first?"
+    name="pb-2026"
+    options={[{ id: "a", label: "Riverside path" }, { id: "b", label: "School playground" }]}
+    bind:selected
+    onsubmit={(id) => postVote(id)}
+  >
+    {#snippet captcha()}<TurnstileWidget /> {/snippet}
+  </VotingWidget>
+-->
+<script>
+  /**
+   * @typedef {{ id: string, label: string, votes?: number }} VoteOption
+   */
+
+  let {
+    /** @type {string} The question (rendered as the fieldset legend). */
+    question = "",
+    /** @type {VoteOption[]} */
+    options = [],
+    /** @type {string | undefined} Bindable selected option id. */
+    selected = $bindable(undefined),
+    /** @type {string} Radio-group name — unique per widget on the page. */
+    name = "vote",
+    /** @type {boolean} Voting period is over. */
+    closed = false,
+    /** @type {boolean} This citizen has already voted. */
+    submitted = false,
+    /** @type {boolean} Voting unavailable (e.g. not eligible / login required). */
+    disabled = false,
+    /** @type {boolean} Render the tally as labelled bars. */
+    showResults = false,
+    /** @type {string} Submit button text (localize it). */
+    submitLabel = "Submit vote",
+    /** @type {string} Heading shown in the submitted state (localize it). */
+    submittedLabel = "Your vote has been recorded.",
+    /** @type {string} Notice shown in the closed state (localize it). */
+    closedLabel = "Voting has closed.",
+    /** @type {string} Reason voting is unavailable, announced (localize it). */
+    disabledReason = "",
+    /** @type {((optionId: string) => void) | undefined} */
+    onsubmit = undefined,
+    /** @type {string} */
+    class: className = "",
+    /** @type {import('svelte').Snippet | undefined} Bot-protection challenge (Turnstile). */
+    captcha = undefined,
+    /** @type {import('svelte').Snippet | undefined} Pseudonymised receipt, shown after voting. */
+    receipt = undefined,
+    ...rest
+  } = $props();
+
+  const canVote = $derived(!closed && !submitted && !disabled);
+  const total = $derived(
+    options.reduce((sum, o) => sum + (o.votes ?? 0), 0),
+  );
+
+  /** @param {number | undefined} votes */
+  const pct = (votes) => (total > 0 ? Math.round(((votes ?? 0) / total) * 100) : 0);
+
+  /** @param {SubmitEvent} e */
+  function handleSubmit(e) {
+    e.preventDefault();
+    if (canVote && selected) onsubmit?.(selected);
+  }
+</script>
+
+<section class="voting-widget {className}" {...rest}>
+  <form class="voting-form" onsubmit={handleSubmit} novalidate>
+    <fieldset class="voting-fieldset" disabled={!canVote}>
+      <legend class="voting-legend">{question}</legend>
+
+      {#if disabled && disabledReason}
+        <p class="voting-reason" role="note">{disabledReason}</p>
+      {/if}
+
+      <ul class="voting-options">
+        {#each options as option (option.id)}
+          <li class="voting-option">
+            <label class="voting-label">
+              <input
+                type="radio"
+                class="voting-radio"
+                {name}
+                value={option.id}
+                bind:group={selected}
+                disabled={!canVote}
+              />
+              <span class="voting-option-text">{option.label}</span>
+              {#if showResults}
+                <span class="voting-pct">{pct(option.votes)}%</span>
+              {/if}
+            </label>
+            {#if showResults}
+              <div class="voting-bar" aria-hidden="true">
+                <div class="voting-bar-fill" style:width={`${pct(option.votes)}%`}></div>
+              </div>
+            {/if}
+          </li>
+        {/each}
+      </ul>
+    </fieldset>
+
+    {#if canVote}
+      {#if captcha}<div class="voting-captcha">{@render captcha()}</div>{/if}
+      <button type="submit" class="voting-submit" disabled={!selected}>
+        {submitLabel}
+      </button>
+    {/if}
+  </form>
+
+  <!-- Status region: confirmation / closed notice land here so AT announces them. -->
+  <div class="voting-status" role="status" aria-live="polite">
+    {#if submitted}
+      <p class="voting-confirm">{submittedLabel}</p>
+      {#if receipt}<div class="voting-receipt">{@render receipt()}</div>{/if}
+    {:else if closed}
+      <p class="voting-closed">{closedLabel}</p>
+    {/if}
+  </div>
+</section>
+
+<style>
+  .voting-widget {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-lg);
+  }
+
+  .voting-form {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-lg);
+  }
+
+  .voting-fieldset {
+    margin: 0;
+    padding: 0;
+    border: 0;
+    min-width: 0;
+  }
+
+  .voting-legend {
+    padding: 0;
+    margin-bottom: var(--space-md);
+    font-family: var(--type-heading-sm-font);
+    font-size: var(--type-heading-sm-size);
+    color: var(--color-text);
+  }
+
+  .voting-reason {
+    margin: 0 0 var(--space-md);
+    font-family: var(--type-body-sm-font);
+    font-size: var(--type-body-sm-size);
+    color: var(--color-text-muted);
+  }
+
+  .voting-options {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-sm);
+  }
+
+  .voting-label {
+    display: flex;
+    align-items: center;
+    gap: var(--space-sm);
+    padding: var(--space-sm) var(--space-md);
+    border: 1px solid var(--color-border);
+    border-radius: var(--radius-md);
+    background: var(--color-surface);
+    cursor: pointer;
+  }
+  /* Selected row reads as chosen without relying on the native dot alone. */
+  .voting-label:has(.voting-radio:checked) {
+    border-color: var(--color-accent);
+    background: var(--color-accent-subtle);
+  }
+  .voting-label:has(.voting-radio:focus-visible) {
+    outline: var(--focus-ring-width) solid var(--focus-ring-color);
+    outline-offset: var(--focus-ring-offset);
+  }
+  .voting-fieldset:disabled .voting-label {
+    cursor: default;
+    opacity: 0.7;
+  }
+
+  .voting-radio {
+    flex-shrink: 0;
+    accent-color: var(--color-accent);
+  }
+
+  .voting-option-text {
+    flex: 1;
+    font-family: var(--type-body-font);
+    font-size: var(--type-body-size);
+    color: var(--color-text);
+  }
+
+  .voting-pct {
+    font-family: var(--type-data-font);
+    font-size: var(--type-data-size);
+    color: var(--color-text-secondary);
+  }
+
+  .voting-bar {
+    height: var(--space-2xs);
+    margin-top: var(--space-2xs);
+    border-radius: var(--radius-pill);
+    background: var(--color-surface-tertiary);
+    overflow: hidden;
+  }
+  .voting-bar-fill {
+    height: 100%;
+    background: var(--color-accent);
+    transition: width var(--duration-normal) var(--easing-default);
+  }
+  @media (prefers-reduced-motion: reduce) {
+    .voting-bar-fill {
+      transition: none;
+    }
+  }
+
+  .voting-submit {
+    align-self: flex-start;
+    padding: var(--space-sm) var(--space-lg);
+    border: 0;
+    border-radius: var(--radius-md);
+    background: var(--color-accent);
+    color: var(--color-text-on-accent);
+    font-family: var(--type-label-font);
+    font-size: var(--type-label-size);
+    cursor: pointer;
+  }
+  .voting-submit:hover:not(:disabled) {
+    background: var(--color-accent-hover);
+  }
+  .voting-submit:focus-visible {
+    outline: var(--focus-ring-width) solid var(--focus-ring-color);
+    outline-offset: var(--focus-ring-offset);
+  }
+  .voting-submit:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+
+  .voting-confirm,
+  .voting-closed {
+    margin: 0;
+    font-family: var(--type-label-font);
+    font-size: var(--type-label-size);
+    color: var(--color-text);
+  }
+  .voting-confirm {
+    color: var(--color-success);
+  }
+
+  .voting-receipt {
+    margin-top: var(--space-sm);
+  }
+</style>

package/components/VotingWidget.svelte.d.ts

@@ -0,0 +1,80 @@
+export default VotingWidget;
+type VotingWidget = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * VotingWidget
+ *
+ * Participation vote panel — the Valongo V10 participation-grid primitive
+ * (participatory budget, consultations, local polls). One question, a radio
+ * group of options, a submit path, and a pseudonymised receipt after voting.
+ * Presentational: it emits `onsubmit(optionId)`; the portal wires that to the
+ * BFF public submit surface (`POST /{app}/public/submit`, voting placement —
+ * #70 M4), and renders the bot-protection challenge into the `captcha` slot.
+ *
+ * States (mutually exclusive vote-ability):
+ *  - open        — radio group + submit (the default)
+ *  - submitted   — confirmation + the `receipt` slot, voting locked
+ *  - closed      — voting period over; results only
+ *  - disabled    — not eligible (e.g. anonymous where login is required);
+ *                  options shown read-only with an announced `disabledReason`
+ * Pass `showResults` to render the tally as labelled bars (typically once
+ * `closed` or `submitted`).
+ *
+ * Accessibility:
+ *  - `<fieldset>` + `<legend>` (the question) groups the options as a native
+ *    radio group — arrow-key navigation and "n of m" come for free.
+ *  - Submit is disabled until an option is chosen; the confirmation + receipt
+ *    land in an `aria-live="polite"` region so a screen reader announces them.
+ *  - Result bars are `aria-hidden`; each option's percentage is in its visible
+ *    text, so the meaning isn't colour/width-only.
+ *  - Radios keep a visible focus ring; reduced-motion disables the bar fill.
+ *
+ * @example
+ * <VotingWidget
+ *   question="Which project should Valongo fund first?"
+ *   name="pb-2026"
+ *   options={[{ id: "a", label: "Riverside path" }, { id: "b", label: "School playground" }]}
+ *   bind:selected
+ *   onsubmit={(id) => postVote(id)}
+ * >
+ *   {#snippet captcha()}<TurnstileWidget /> {/snippet}
+ * </VotingWidget>
+ */
+declare const VotingWidget: import("svelte").Component<{
+    question?: string;
+    options?: any[];
+    selected?: any;
+    name?: string;
+    closed?: boolean;
+    submitted?: boolean;
+    disabled?: boolean;
+    showResults?: boolean;
+    submitLabel?: string;
+    submittedLabel?: string;
+    closedLabel?: string;
+    disabledReason?: string;
+    onsubmit?: any;
+    class?: string;
+    captcha?: any;
+    receipt?: any;
+} & Record<string, any>, {}, "selected">;
+type $$ComponentProps = {
+    question?: string;
+    options?: any[];
+    selected?: any;
+    name?: string;
+    closed?: boolean;
+    submitted?: boolean;
+    disabled?: boolean;
+    showResults?: boolean;
+    submitLabel?: string;
+    submittedLabel?: string;
+    closedLabel?: string;
+    disabledReason?: string;
+    onsubmit?: any;
+    class?: string;
+    captcha?: any;
+    receipt?: any;
+} & Record<string, any>;

package/components/WidgetGrid.svelte

@@ -0,0 +1,83 @@
+<!--
+  @component WidgetGrid
+
+  Responsive dashboard layout for the citizen portal's `landing` /
+  information-portal pages, where blocks vary in weight — a hero stat, a list of
+  recent consultations, a map, a voting panel. Where CardGrid lays out equal
+  cards, WidgetGrid is a column grid whose children may declare a span, so a
+  feature widget can sit beside two narrow ones.
+
+  Collapses to one column on small screens (every widget full-width), goes to
+  two at tablet, and to `columns` at desktop. Children opt into width via the
+  span helper classes (applied to the direct child, e.g. a `<Card>` or
+  `<section>`):
+
+   - `widget-span-2`  — span two columns from tablet up
+   - `widget-span-full` — span the full row at every breakpoint
+
+  Layout only — it sets no landmark and imposes no semantics; the page supplies
+  headings and regions.
+
+  @example
+  <WidgetGrid columns="3">
+    <section class="widget-span-2"><Hero ... /></section>
+    <Card>…</Card>
+    <Card class="widget-span-full">…</Card>
+  </WidgetGrid>
+-->
+<script>
+  let {
+    /** @type {'2' | '3' | '4'} Column count at the desktop breakpoint. */
+    columns = "3",
+    /** @type {string} */
+    class: className = "",
+    /** @type {import('svelte').Snippet | undefined} */
+    children = undefined,
+    ...rest
+  } = $props();
+</script>
+
+<div class="widget-grid widget-grid-{columns} {className}" {...rest}>
+  {#if children}{@render children()}{/if}
+</div>
+
+<style>
+  .widget-grid {
+    display: grid;
+    gap: var(--grid-gutter);
+    grid-template-columns: 1fr;
+    align-items: start;
+  }
+
+  /* Keep widgets from blowing out their track. */
+  .widget-grid > :global(*) {
+    min-width: 0;
+  }
+
+  /* ─── Tablet: two columns, span helpers come alive ─── */
+  @media (min-width: 768px) {
+    .widget-grid-2,
+    .widget-grid-3,
+    .widget-grid-4 {
+      grid-template-columns: repeat(2, 1fr);
+    }
+    .widget-grid > :global(.widget-span-2) {
+      grid-column: span 2;
+    }
+  }
+
+  /* ─── Desktop: open up to the configured column count ─── */
+  @media (min-width: 1024px) {
+    .widget-grid-3 {
+      grid-template-columns: repeat(3, 1fr);
+    }
+    .widget-grid-4 {
+      grid-template-columns: repeat(4, 1fr);
+    }
+  }
+
+  /* Full-width span at every breakpoint. */
+  .widget-grid > :global(.widget-span-full) {
+    grid-column: 1 / -1;
+  }
+</style>

package/components/WidgetGrid.svelte.d.ts

@@ -0,0 +1,42 @@
+export default WidgetGrid;
+type WidgetGrid = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * WidgetGrid
+ *
+ * Responsive dashboard layout for the citizen portal's `landing` /
+ * information-portal pages, where blocks vary in weight — a hero stat, a list of
+ * recent consultations, a map, a voting panel. Where CardGrid lays out equal
+ * cards, WidgetGrid is a column grid whose children may declare a span, so a
+ * feature widget can sit beside two narrow ones.
+ *
+ * Collapses to one column on small screens (every widget full-width), goes to
+ * two at tablet, and to `columns` at desktop. Children opt into width via the
+ * span helper classes (applied to the direct child, e.g. a `<Card>` or
+ * `<section>`):
+ *
+ *  - `widget-span-2`  — span two columns from tablet up
+ *  - `widget-span-full` — span the full row at every breakpoint
+ *
+ * Layout only — it sets no landmark and imposes no semantics; the page supplies
+ * headings and regions.
+ *
+ * @example
+ * <WidgetGrid columns="3">
+ *   <section class="widget-span-2"><Hero ... /></section>
+ *   <Card>…</Card>
+ *   <Card class="widget-span-full">…</Card>
+ * </WidgetGrid>
+ */
+declare const WidgetGrid: import("svelte").Component<{
+    columns?: string;
+    class?: string;
+    children?: any;
+} & Record<string, any>, {}, "">;
+type $$ComponentProps = {
+    columns?: string;
+    class?: string;
+    children?: any;
+} & Record<string, any>;

package/components/index.js

@@ -33,6 +33,19 @@ export { default as List } from "./List.svelte";
 export { default as ListItem } from "./ListItem.svelte";
 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 SiteFooter } from "./SiteFooter.svelte";
+export { default as SkipLink } from "./SkipLink.svelte";
+export { default as ServiceNavigation } from "./ServiceNavigation.svelte";
+export { default as Link } from "./Link.svelte";
+export { default as Hero } from "./Hero.svelte";
+export { default as ContentBlock } from "./ContentBlock.svelte";
+export { default as StatusTimeline } from "./StatusTimeline.svelte";
+export { default as WidgetGrid } from "./WidgetGrid.svelte";
+export { default as VotingWidget } from "./VotingWidget.svelte";
+
 // Containers
 export { default as Card } from "./Card.svelte";
 export { default as Panel } from "./Panel.svelte";

package/package.json

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

package/tokens/themes/valongo.css

@@ -0,0 +1,44 @@
+/*
+ * aiaiai Design System — Tier 1: Tenant Theme — Município de Valongo
+ *
+ * Example citizen-portal tenant theme (#7 portal template system). Demonstrates
+ * the Tier-1 contract: a municipality re-skins brand tokens only; structure,
+ * typography, spacing, motion, radius, and a11y stay frozen and
+ * conformance-checkable (Designers Italia "Modello Comuni" model).
+ *
+ * In production these overrides come from the tenant's `portal` ontology row
+ * and are injected at runtime by the portal's hooks.server.ts; this static
+ * file is the seed/example.
+ *
+ * Tier-1 rules: override < 20 semantic tokens; change accent + surface tint;
+ * keep everything else.
+ *
+ * Apply via: <html data-theme="valongo">
+ */
+
+[data-theme="valongo"] {
+  /* ─── Accent: Valongo civic green ─── */
+  --color-accent: #2e7d32;
+  --color-accent-hover: #1b5e20;
+  --color-accent-subtle: #eaf4ea;
+
+  /* ─── Surface: warm neutral ─── */
+  --color-surface: #ffffff;
+  --color-surface-secondary: #f4f6f3;
+  --color-surface-tertiary: #e8ece6;
+
+  /* ─── Borders ─── */
+  --color-border: #d7ded3;
+  --color-border-strong: #abb8a4;
+
+  /* ─── Text ─── */
+  --color-text: #1c241b;
+  --color-text-secondary: #44513f;
+  --color-text-muted: #71806b;
+
+  /* ─── Overlay + focus follow the brand ─── */
+  --color-overlay: rgba(28, 36, 27, 0.5);
+  --focus-ring-color: var(--color-accent);
+
+  /* Total overrides: 14 tokens. Still an aiaiai product, in Valongo's colours. */
+}