@aiaiai-pt/design-system 0.8.3 → 0.9.0

package/components/ValueSourcePicker.svelte

@@ -81,6 +81,15 @@
       "function",
       "expression",
     ],
+    /**
+     * Mode pre-selected when `value === null`, so the operator lands
+     * on an editable affordance instead of a "Pick a source"
+     * placeholder. The bound `value` stays `null` until the operator
+     * interacts — form dirty-tracking and consumer-side null intent
+     * survive. The default is forbidden if it isn't in `allowed`.
+     * @type {ValueSourceMode | null}
+     */
+    defaultMode = null,
     /** @type {ValueSourceContext} */
     context = {},
     /** @type {string | undefined} */
@@ -137,6 +146,19 @@
     currentMode !== null && !allowed.includes(currentMode),
   );
 
+  // Effective view of the picker — uses `defaultMode` as a fallback
+  // when there's no stored value, so the operator sees a mode +
+  // affordance pre-selected. Read-only: `value` stays null until the
+  // operator interacts. Forbidden defaults silently fall back to the
+  // null placeholder rather than rendering a mode that isn't allowed.
+  const effectiveValue = $derived.by(() => {
+    if (value !== null) return value;
+    if (defaultMode === null) return null;
+    if (!allowed.includes(defaultMode)) return null;
+    return makeBlankForMode(defaultMode);
+  });
+  const effectiveMode = $derived(effectiveValue?.mode ?? null);
+
   function emit(next) {
     value = next;
     onchange?.(next);
@@ -144,7 +166,9 @@
 
   function pickMode(/** @type {string} */ next) {
     const mode = /** @type {ValueSourceMode} */ (next);
-    if (mode === currentMode) return;
+    // Compare against the effective mode so re-picking the
+    // pre-selected default is a no-op rather than an emit.
+    if (mode === effectiveMode) return;
     emit(makeBlankForMode(mode));
   }
 
@@ -374,8 +398,8 @@
       <Select
         id={`${groupId}-mode`}
         size="sm"
-        placeholder={value === null ? "Pick a source" : undefined}
-        value={currentMode ?? ""}
+        placeholder={effectiveValue === null ? "Pick a source" : undefined}
+        value={effectiveMode ?? ""}
         options={modeOptions}
         onchange={pickMode}
         {disabled}
@@ -388,90 +412,90 @@
           <Badge variant="error">no longer allowed: {MODE_LABEL[value.mode]}</Badge>
           <Button variant="ghost" size="sm" onclick={clear}>Clear</Button>
         </div>
-      {:else if value === null}
+      {:else if effectiveValue === null}
         <span class="vsp-placeholder">{MODE_DESCRIPTION[allowed[0]] ?? ""}</span>
-      {:else if value.mode === "literal"}
+      {:else if effectiveValue.mode === "literal"}
         <Input
           size="sm"
           placeholder={literalPlaceholder(expectedType)}
-          value={String(value.value ?? "")}
+          value={String(effectiveValue.value ?? "")}
           oninput={(e) => emit({ mode: "literal", value: coerceLiteral(/** @type {HTMLInputElement} */ (e.target).value, expectedType) })}
           {disabled}
         />
-      {:else if value.mode === "parameter"}
+      {:else if effectiveValue.mode === "parameter"}
         <Combobox
           size="sm"
           placeholder="Pick a parameter"
           items={paramOptions()}
-          value={value.key}
+          value={effectiveValue.key}
           onchange={(k) => emit({ mode: "parameter", key: k })}
           {disabled}
         />
-      {:else if value.mode === "entity-field"}
+      {:else if effectiveValue.mode === "entity-field"}
         <Combobox
           size="sm"
           placeholder="Pick a field"
           items={entityFieldOptions()}
-          value={value.field}
+          value={effectiveValue.field}
           onchange={(f) => emit({ mode: "entity-field", field: f })}
           {disabled}
         />
-      {:else if value.mode === "user-field"}
+      {:else if effectiveValue.mode === "user-field"}
         <Combobox
           size="sm"
           placeholder="Pick a user claim"
           items={userFieldOptions()}
-          value={value.key}
+          value={effectiveValue.key}
           onchange={(k) => emit({ mode: "user-field", key: k })}
           {disabled}
         />
-      {:else if value.mode === "now"}
+      {:else if effectiveValue.mode === "now"}
         <Badge variant="info">$now — current UTC timestamp</Badge>
-      {:else if value.mode === "source-id"}
+      {:else if effectiveValue.mode === "source-id"}
         <Badge variant="info">$source.id — id of the entity being acted upon</Badge>
-      {:else if value.mode === "config-list"}
+      {:else if effectiveValue.mode === "config-list"}
         <Combobox
           size="sm"
           placeholder="Pick a config type"
           items={configTypeOptions()}
-          value={value.configType}
+          value={effectiveValue.configType}
           onchange={(c) => emit({ mode: "config-list", configType: c })}
           {disabled}
         />
         <Badge variant="neutral">list</Badge>
-      {:else if value.mode === "expression"}
+      {:else if effectiveValue.mode === "expression"}
         <Input
           size="sm"
           placeholder="$entity.X + 1"
-          value={value.expr}
+          value={effectiveValue.expr}
           oninput={(e) => emit({ mode: "expression", expr: /** @type {HTMLInputElement} */ (e.target).value })}
           {disabled}
         />
-      {:else if value.mode === "created-field"}
+      {:else if effectiveValue.mode === "created-field"}
         <div class="vsp-inline">
           <Combobox
             size="sm"
             placeholder="prior create"
             items={priorCreateOptions()}
-            value={String(value.index)}
-            onchange={(i) => emit({ mode: "created-field", index: Number(i), field: value.field })}
+            value={String(effectiveValue.index)}
+            onchange={(i) => emit({ mode: "created-field", index: Number(i), field: /** @type {{mode:'created-field',index:number,field:string}} */ (effectiveValue).field })}
             {disabled}
           />
           <Combobox
             size="sm"
             placeholder="field"
             items={priorCreateFieldOptions()}
-            value={value.field}
-            onchange={(f) => emit({ mode: "created-field", index: value.index, field: f })}
+            value={effectiveValue.field}
+            onchange={(f) => emit({ mode: "created-field", index: /** @type {{mode:'created-field',index:number,field:string}} */ (effectiveValue).index, field: f })}
             {disabled}
           />
         </div>
-      {:else if value.mode === "function"}
+      {:else if effectiveValue.mode === "function"}
         <Combobox
           size="sm"
           placeholder="Pick a function"
           items={functionOptions()}
-          value={value.name}
+          value={effectiveValue.name}
           onchange={(n) => emit({ mode: "function", name: n, args: {} })}
           {disabled}
         />

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";