@aiaiai-pt/design-system 0.33.0 → 0.35.0

package/components/EChart.svelte

@@ -0,0 +1,266 @@
+<!--
+  @component EChart
+
+  A horizontal bar chart for a single categorical aggregate (votes per proposal,
+  reports per category, …) rendered with Apache ECharts, that SHIPS ITS DATA
+  TABLE — same a11y contract as `ResultsChart`. The ECharts canvas is decorative
+  (`aria-hidden`); the accompanying `<table>` is the accessible source of truth,
+  always rendered server-side and client-side, so the data is reachable with
+  JS off, CSS off, at any zoom, and to assistive tech. This is a hard
+  requirement (WCAG / ARTE: a chart must not be the only encoding of its data),
+  not a toggle.
+
+  ECharts is LAZY-loaded: `echarts/core` + only the BarChart / Grid / Tooltip
+  modules + the canvas renderer are dynamically `import()`ed inside the mount
+  effect, so the heavy library lands in its OWN async chunk — a page that never
+  mounts a chart never pays for it. Effects are client-only in Svelte 5, so the
+  canvas is never touched during SSR.
+
+  Vertical-agnostic: `items` is already shaped to `{ label, value }` by the
+  consumer (a widget over a public aggregate VIEW). Themed from the live
+  `--color-*` semantic tokens read off the container, and re-themed on
+  `data-theme` / `prefers-color-scheme` change (#244), so dark / high-contrast
+  schemes ride through. Soft-empty: no items → renders nothing.
+
+  @example
+  <EChart
+    caption="Votes per proposal"
+    labelHeader="Proposal"
+    valueHeader="Votes"
+    items={[
+      { label: "Ciclovia da Marginal", value: 1284 },
+      { label: "Parque infantil de Gaia", value: 967 },
+    ]}
+    locale="pt"
+  />
+-->
+<script module>
+  /**
+   * @typedef {{ label: string, value: number }} ChartItem
+   */
+</script>
+
+<script>
+  import { watchTheme } from "./map-utils.js";
+
+  let {
+    /** @type {ChartItem[]} The categorical rows to plot. */
+    items = [],
+    /** @type {string} Accessible caption / heading for the chart + table. */
+    caption = "Results",
+    /** @type {string} Column header for the category (localize it). */
+    labelHeader = "Item",
+    /** @type {string} Column header for the value (localize it). */
+    valueHeader = "Value",
+    /** @type {string} BCP-47 locale for number formatting. */
+    locale = "en",
+    /** @type {string} CSS block-size for the chart canvas. */
+    height = "20rem",
+    /** @type {string} */
+    class: className = "",
+    ...rest
+  } = $props();
+
+  /** @param {number} value @returns {string} */
+  function fmt(value) {
+    return new Intl.NumberFormat(locale).format(value);
+  }
+
+  /** @type {HTMLElement | undefined} */
+  let container = $state();
+
+  // The ECharts instance + the canvas-renderer chart option are owned by the
+  // mount effect; this effect (re-)builds the option whenever `items`, the
+  // locale, or the theme change. `_chart` is hoisted so the data effect can
+  // re-setOption without re-initialising the canvas.
+  /** @type {import('echarts/core').EChartsType | undefined} */
+  let _chart = $state();
+
+  /** Build the ECharts option from current items + the container's tokens. */
+  function buildOption() {
+    const el = container;
+    if (!el) return {};
+    const cs = getComputedStyle(el);
+    const token = (name, fallback) => {
+      const v = cs.getPropertyValue(name).trim();
+      return v || fallback;
+    };
+    const accent = token("--color-accent", "#2563eb");
+    const textPrimary = token("--color-text-primary", "#1f2937");
+    const textSecondary = token("--color-text-secondary", "#6b7280");
+    const border = token("--color-border", "#e5e7eb");
+
+    // ECharts plots the category axis bottom-up; reverse so the highest value
+    // sits at the top (matching ResultsChart's top-down order). `items` is
+    // already sorted desc by the consumer.
+    const ordered = [...items].reverse();
+
+    return {
+      animation: false,
+      grid: { left: 8, right: 16, top: 8, bottom: 8, containLabel: true },
+      tooltip: {
+        trigger: "item",
+        /** @param {{ name: string, value: number }} p */
+        formatter: (p) => `${p.name}: ${fmt(p.value)}`,
+      },
+      xAxis: {
+        type: "value",
+        axisLabel: { color: textSecondary, formatter: (/** @type {number} */ v) => fmt(v) },
+        axisLine: { lineStyle: { color: border } },
+        splitLine: { lineStyle: { color: border } },
+      },
+      yAxis: {
+        type: "category",
+        data: ordered.map((it) => it.label),
+        axisLabel: { color: textPrimary },
+        axisLine: { lineStyle: { color: border } },
+        axisTick: { show: false },
+      },
+      series: [
+        {
+          type: "bar",
+          data: ordered.map((it) => it.value),
+          itemStyle: { color: accent, borderRadius: [0, 4, 4, 0] },
+          barMaxWidth: 28,
+        },
+      ],
+    };
+  }
+
+  $effect(() => {
+    if (!container) return;
+
+    let disposed = false;
+    /** @type {import('echarts/core').EChartsType | undefined} */
+    let chart;
+    /** @type {ResizeObserver | undefined} */
+    let ro;
+    /** @type {(() => void) | undefined} */
+    let disposeTheme;
+
+    (async () => {
+      try {
+        const [core, charts, components, renderers] = await Promise.all([
+          import("echarts/core"),
+          import("echarts/charts"),
+          import("echarts/components"),
+          import("echarts/renderers"),
+        ]);
+        if (disposed || !container) return;
+
+        core.use([
+          charts.BarChart,
+          components.GridComponent,
+          components.TooltipComponent,
+          renderers.CanvasRenderer,
+        ]);
+
+        chart = core.init(container, null, { renderer: "canvas" });
+        _chart = chart;
+        chart.setOption(buildOption());
+
+        ro = new ResizeObserver(() => chart?.resize());
+        ro.observe(container);
+
+        disposeTheme = watchTheme(() => chart?.setOption(buildOption()));
+      } catch (err) {
+        // Fail soft: the <table> below is the accessible source of truth, so a
+        // failed chart load degrades to data-only, never to a broken page.
+        // eslint-disable-next-line no-console
+        console.error("EChart: failed to render", err);
+      }
+    })();
+
+    return () => {
+      disposed = true;
+      disposeTheme?.();
+      ro?.disconnect();
+      chart?.dispose();
+      _chart = undefined;
+    };
+  });
+
+  // Re-apply the option when items / locale change after mount (the canvas
+  // persists; only the data is swapped). Guarded on `_chart` so it no-ops
+  // before init and after dispose.
+  $effect(() => {
+    // touch reactive deps so the effect re-runs when they change
+    void items;
+    void locale;
+    if (_chart) _chart.setOption(buildOption());
+  });
+</script>
+
+{#if items.length > 0}
+  <figure class="echart {className}" aria-label={caption} {...rest}>
+    <!-- Decorative visual: the data lives in the table below. -->
+    <div
+      class="echart-canvas"
+      bind:this={container}
+      aria-hidden="true"
+      style="block-size: {height}"
+    ></div>
+
+    <!-- Accessible source of truth — always rendered (ARTE #3/#6). Named via
+         aria-label, not a <caption>: position:absolute/clip is unreliable on a
+         display:table-caption element (it leaks visibly in some engines). -->
+    <table class="echart-table" aria-label={caption}>
+      <thead>
+        <tr>
+          <th scope="col">{labelHeader}</th>
+          <th scope="col">{valueHeader}</th>
+        </tr>
+      </thead>
+      <tbody>
+        {#each items as item, i (item.label + i)}
+          <tr>
+            <th scope="row">{item.label}</th>
+            <td>{fmt(item.value)}</td>
+          </tr>
+        {/each}
+      </tbody>
+    </table>
+  </figure>
+{/if}
+
+<style>
+  .echart {
+    margin: 0;
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-md);
+  }
+
+  .echart-canvas {
+    inline-size: 100%;
+  }
+
+  .echart-table {
+    inline-size: 100%;
+    border-collapse: collapse;
+    font-size: var(--type-body-sm-size);
+  }
+
+  .echart-table th,
+  .echart-table td {
+    text-align: start;
+    padding: var(--space-2xs) var(--space-xs);
+    border-block-end: 1px solid var(--color-border);
+  }
+
+  .echart-table thead th {
+    color: var(--color-text-secondary);
+    font-weight: 600;
+  }
+
+  .echart-table tbody th {
+    font-weight: 400;
+    color: var(--color-text-primary);
+  }
+
+  .echart-table td {
+    text-align: end;
+    font-variant-numeric: tabular-nums;
+    color: var(--color-text-primary);
+  }
+</style>

package/components/EChart.svelte.d.ts

@@ -0,0 +1,63 @@
+export default EChart;
+export type ChartItem = {
+    label: string;
+    value: number;
+};
+type EChart = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * EChart
+ *
+ * A horizontal bar chart for a single categorical aggregate (votes per proposal,
+ * reports per category, …) rendered with Apache ECharts, that SHIPS ITS DATA
+ * TABLE — same a11y contract as `ResultsChart`. The ECharts canvas is decorative
+ * (`aria-hidden`); the accompanying `<table>` is the accessible source of truth,
+ * always rendered server-side and client-side, so the data is reachable with
+ * JS off, CSS off, at any zoom, and to assistive tech. This is a hard
+ * requirement (WCAG / ARTE: a chart must not be the only encoding of its data),
+ * not a toggle.
+ *
+ * ECharts is LAZY-loaded: `echarts/core` + only the BarChart / Grid / Tooltip
+ * modules + the canvas renderer are dynamically `import()`ed inside the mount
+ * effect, so the heavy library lands in its OWN async chunk — a page that never
+ * mounts a chart never pays for it. Effects are client-only in Svelte 5, so the
+ * canvas is never touched during SSR.
+ *
+ * Vertical-agnostic: `items` is already shaped to `{ label, value }` by the
+ * consumer (a widget over a public aggregate VIEW). Themed from the live
+ * `--color-*` semantic tokens read off the container, and re-themed on
+ * `data-theme` / `prefers-color-scheme` change (#244), so dark / high-contrast
+ * schemes ride through. Soft-empty: no items → renders nothing.
+ *
+ * @example
+ * <EChart
+ *   caption="Votes per proposal"
+ *   labelHeader="Proposal"
+ *   valueHeader="Votes"
+ *   items={[
+ *     { label: "Ciclovia da Marginal", value: 1284 },
+ *     { label: "Parque infantil de Gaia", value: 967 },
+ *   ]}
+ *   locale="pt"
+ * />
+ */
+declare const EChart: import("svelte").Component<{
+    items?: any[];
+    caption?: string;
+    labelHeader?: string;
+    valueHeader?: string;
+    locale?: string;
+    height?: string;
+    class?: string;
+} & Record<string, any>, {}, "">;
+type $$ComponentProps = {
+    items?: any[];
+    caption?: string;
+    labelHeader?: string;
+    valueHeader?: string;
+    locale?: string;
+    height?: string;
+    class?: string;
+} & Record<string, any>;

package/components/index.js

@@ -102,6 +102,9 @@ export { default as PhaseTimeline } from "./PhaseTimeline.svelte";
 // encoding of its data); RankingBoard is a semantic ordered leaderboard.
 export { default as RankingBoard } from "./RankingBoard.svelte";
 export { default as ResultsChart } from "./ResultsChart.svelte";
+// EChart (#498) — the ECharts-backed sibling of ResultsChart: same data-table
+// a11y contract, lazy-loads echarts into its own async chunk.
+export { default as EChart } from "./EChart.svelte";
 
 // Account / preferences (#105 Phase 5) — the citizen account area's
 // notification-preferences panel: a toggle list over a citizen's subscriptions.

package/components/renderer/EChartWidget.svelte

@@ -0,0 +1,78 @@
+<script lang="ts">
+  import EChart from "../EChart.svelte";
+  import type { WidgetProps } from "./types";
+  import { toRankedItems } from "./aggregate";
+
+  // `chart` widget (#498) — an ECharts bar chart over a public aggregate VIEW,
+  // the richer sibling of `results-chart` (pure-CSS bars). Type-ranked on
+  // `kind: "aggregate"` (out-ranks the kind default) so a `type: "chart"` block
+  // renders the ECharts widget while `type: "results-chart"` renders the CSS
+  // one. Same a11y contract: EChart ships its data table (ARTE #3/#6 — a chart
+  // is never the only encoding). Same data path as ResultsChartWidget: reads
+  // the `{ items }` rows and projects `{ label, value }` via `toRankedItems`,
+  // so NO resolve-data / provider change is needed. Soft-empty on no rows.
+  let { data, props, ownsH1, locale }: WidgetProps = $props();
+
+  const rows = $derived(
+    data && typeof data === "object" && Array.isArray((data as { items?: unknown }).items)
+      ? ((data as { items: Record<string, unknown>[] }).items)
+      : [],
+  );
+
+  const labelField = $derived(
+    typeof props.label_field === "string" && props.label_field
+      ? props.label_field
+      : "label",
+  );
+  const valueField = $derived(
+    typeof props.value_field === "string" && props.value_field
+      ? props.value_field
+      : "value",
+  );
+  const limit = $derived(
+    typeof props.limit === "number" && props.limit > 0 ? props.limit : 0,
+  );
+
+  const items = $derived(
+    toRankedItems(rows, { labelField, valueField, limit }),
+  );
+
+  const heading = $derived(
+    typeof props.title === "string" && props.title ? props.title : "",
+  );
+  const caption = $derived(heading || "Results");
+  const labelHeader = $derived(
+    typeof props.label_header === "string" && props.label_header
+      ? props.label_header
+      : "Item",
+  );
+  const valueHeader = $derived(
+    typeof props.value_header === "string" && props.value_header
+      ? props.value_header
+      : "Value",
+  );
+</script>
+
+{#if items.length > 0}
+  <section class="widget-band">
+    {#if heading}
+      {#if ownsH1}<h1>{heading}</h1>{:else}<h2>{heading}</h2>{/if}
+    {/if}
+    <EChart
+      {items}
+      {caption}
+      {labelHeader}
+      {valueHeader}
+      locale={locale ?? "en"}
+    />
+  </section>
+{/if}
+
+<style>
+  .widget-band {
+    width: 100%;
+    max-width: var(--content-width-narrow);
+    margin-inline: auto;
+    padding-inline: var(--content-padding-x);
+  }
+</style>

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

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

package/components/renderer/ResultsChartWidget.svelte

@@ -0,0 +1,77 @@
+<script lang="ts">
+  import ResultsChart from "../ResultsChart.svelte";
+  import type { WidgetProps } from "./types";
+  import { toRankedItems } from "./aggregate";
+
+  // `results-chart` widget (#105 Phase 4) — a bar chart over a public aggregate
+  // VIEW that SHIPS its data table (ARTE #3/#6: a chart is never the only
+  // encoding). Type-ranked on `kind: "aggregate"` (out-ranks the board default)
+  // so a `type: "results-chart"` block renders the chart while the bare kind
+  // renders the board. Vertical-agnostic: `props.label_field` / `value_field`
+  // name the view columns; `props.label_header` / `value_header` localise the
+  // table headers. Soft-empty on no rows (optional slot). Flush band.
+  let { data, props, ownsH1, locale }: WidgetProps = $props();
+
+  const rows = $derived(
+    data && typeof data === "object" && Array.isArray((data as { items?: unknown }).items)
+      ? ((data as { items: Record<string, unknown>[] }).items)
+      : [],
+  );
+
+  const labelField = $derived(
+    typeof props.label_field === "string" && props.label_field
+      ? props.label_field
+      : "label",
+  );
+  const valueField = $derived(
+    typeof props.value_field === "string" && props.value_field
+      ? props.value_field
+      : "value",
+  );
+  const limit = $derived(
+    typeof props.limit === "number" && props.limit > 0 ? props.limit : 0,
+  );
+
+  const items = $derived(
+    toRankedItems(rows, { labelField, valueField, limit }),
+  );
+
+  const heading = $derived(
+    typeof props.title === "string" && props.title ? props.title : "",
+  );
+  const caption = $derived(heading || "Results");
+  const labelHeader = $derived(
+    typeof props.label_header === "string" && props.label_header
+      ? props.label_header
+      : "Item",
+  );
+  const valueHeader = $derived(
+    typeof props.value_header === "string" && props.value_header
+      ? props.value_header
+      : "Value",
+  );
+</script>
+
+{#if items.length > 0}
+  <section class="widget-band">
+    {#if heading}
+      {#if ownsH1}<h1>{heading}</h1>{:else}<h2>{heading}</h2>{/if}
+    {/if}
+    <ResultsChart
+      {items}
+      {caption}
+      {labelHeader}
+      {valueHeader}
+      locale={locale ?? "en"}
+    />
+  </section>
+{/if}
+
+<style>
+  .widget-band {
+    width: 100%;
+    max-width: var(--content-width-narrow);
+    margin-inline: auto;
+    padding-inline: var(--content-padding-x);
+  }
+</style>

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

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

package/components/renderer/StatGridWidget.svelte

@@ -0,0 +1,33 @@
+<script lang="ts">
+  import StatGrid from "../StatGrid.svelte";
+  import StatCard from "../StatCard.svelte";
+  import type { WidgetProps } from "./types";
+
+  // `kpi` widget — public stat grid (counts, KPIs). Adapts a list of stat
+  // items into DS StatCards inside a StatGrid. The public KPI read endpoint is
+  // not wired yet (resolveData fails closed for `kind: "kpi"`); registered here
+  // and fed once a slice adds the surface. Defensive over `data` (live) /
+  // `props` (seeded preview).
+  let { data, props }: WidgetProps = $props();
+
+  interface Stat {
+    label?: string;
+    value?: string;
+    variant?: string;
+  }
+
+  const view = $derived((data ?? {}) as Record<string, unknown>);
+  const stats = $derived<Stat[]>(
+    (Array.isArray(view.stats)
+      ? view.stats
+      : Array.isArray(props.stats)
+        ? props.stats
+        : []) as Stat[],
+  );
+</script>
+
+<StatGrid>
+  {#each stats as stat (stat.label)}
+    <StatCard label={stat.label} value={stat.value} variant={stat.variant} />
+  {/each}
+</StatGrid>

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

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

package/components/renderer/aggregate.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Aggregate-view row shaping (#105 Phase 4) — PURE, vertical-agnostic.
+ *
+ * Turns the rows of a public aggregate VIEW (served by the BFF public-view lane,
+ * #250 M3 — `{ items: [{ <label_field>, <value_field>, … }] }`) into the
+ * `{ label, value }` shape the DS `RankingBoard` / `ResultsChart` render, sorted
+ * by value descending and optionally capped. Nothing here is civic-specific:
+ * the label/value columns are config (`label_field` / `value_field`), so any
+ * `group_by + count/sum` view (votes per proposal, reports per category,
+ * consumption per meter) becomes a chart/board from config alone.
+ *
+ * Coercion is deliberate and fail-soft: a missing/blank label falls back to the
+ * empty string (the widget decides whether to drop it), a non-numeric value
+ * coerces to 0 — an aggregate read never throws on a stray row.
+ */
+export interface RankedItem {
+    label: string;
+    value: number;
+}
+export interface ToRankedOptions {
+    /** Key in each row holding the category label. Default `label`. */
+    labelField?: string;
+    /** Key holding the numeric aggregate. Default `value`. */
+    valueField?: string;
+    /** Cap the result to the top-N after sorting. 0/absent → no cap. */
+    limit?: number;
+    /** Drop rows whose label coerces to empty. Default true. */
+    dropBlankLabels?: boolean;
+}
+/**
+ * Map raw view rows → sorted `{ label, value }`. Stable sort by value desc
+ * (ties keep input order); rows are never mutated.
+ */
+export declare function toRankedItems(rows: ReadonlyArray<Record<string, unknown>>, opts?: ToRankedOptions): RankedItem[];

package/components/renderer/aggregate.ts

@@ -0,0 +1,72 @@
+/**
+ * Aggregate-view row shaping (#105 Phase 4) — PURE, vertical-agnostic.
+ *
+ * Turns the rows of a public aggregate VIEW (served by the BFF public-view lane,
+ * #250 M3 — `{ items: [{ <label_field>, <value_field>, … }] }`) into the
+ * `{ label, value }` shape the DS `RankingBoard` / `ResultsChart` render, sorted
+ * by value descending and optionally capped. Nothing here is civic-specific:
+ * the label/value columns are config (`label_field` / `value_field`), so any
+ * `group_by + count/sum` view (votes per proposal, reports per category,
+ * consumption per meter) becomes a chart/board from config alone.
+ *
+ * Coercion is deliberate and fail-soft: a missing/blank label falls back to the
+ * empty string (the widget decides whether to drop it), a non-numeric value
+ * coerces to 0 — an aggregate read never throws on a stray row.
+ */
+
+export interface RankedItem {
+  label: string;
+  value: number;
+}
+
+export interface ToRankedOptions {
+  /** Key in each row holding the category label. Default `label`. */
+  labelField?: string;
+  /** Key holding the numeric aggregate. Default `value`. */
+  valueField?: string;
+  /** Cap the result to the top-N after sorting. 0/absent → no cap. */
+  limit?: number;
+  /** Drop rows whose label coerces to empty. Default true. */
+  dropBlankLabels?: boolean;
+}
+
+function toNumber(value: unknown): number {
+  if (typeof value === "number") return Number.isFinite(value) ? value : 0;
+  if (typeof value === "string" && value.trim() !== "") {
+    const n = Number(value);
+    return Number.isFinite(n) ? n : 0;
+  }
+  return 0;
+}
+
+/**
+ * Map raw view rows → sorted `{ label, value }`. Stable sort by value desc
+ * (ties keep input order); rows are never mutated.
+ */
+export function toRankedItems(
+  rows: ReadonlyArray<Record<string, unknown>>,
+  opts: ToRankedOptions = {},
+): RankedItem[] {
+  const labelField = opts.labelField || "label";
+  const valueField = opts.valueField || "value";
+  const dropBlank = opts.dropBlankLabels !== false;
+
+  const mapped = rows.map((row) => ({
+    label: row[labelField] == null ? "" : String(row[labelField]),
+    value: toNumber(row[valueField]),
+  }));
+
+  const kept = dropBlank ? mapped.filter((it) => it.label !== "") : mapped;
+
+  // Stable desc sort: decorate with the original index so equal values keep
+  // their input order (Array.prototype.sort is spec-stable, but the index tie-
+  // break documents the intent and is robust to value-equality edge cases).
+  const sorted = kept
+    .map((it, i) => ({ it, i }))
+    .sort((a, b) => b.it.value - a.it.value || a.i - b.i)
+    .map(({ it }) => it);
+
+  return opts.limit && opts.limit > 0
+    ? sorted.slice(0, Math.floor(opts.limit))
+    : sorted;
+}