@aiaiai-pt/design-system 0.34.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/registry.ts

@@ -22,6 +22,7 @@ import {
 } from "./dispatch";
 import type { Block, OntologySchema, WidgetKind, WidgetProps } from "./types";
 
+import EChartWidget from "./EChartWidget.svelte";
 import ResultsChartWidget from "./ResultsChartWidget.svelte";
 import StatGridWidget from "./StatGridWidget.svelte";
 
@@ -67,6 +68,7 @@ const _entries: RegistryEntry<WidgetComponent>[] = [
   // DS base: the two clean widgets shipped by this package.
   byKind("stat-grid", "kpi", StatGridWidget),
   byTypeOnKind("results-chart", "aggregate", ResultsChartWidget),
+  byTypeOnKind("chart", "aggregate", EChartWidget),
 ];
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiaiai-pt/design-system",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "Design system tokens and Svelte components for aiaiai products",
   "license": "MIT",
   "type": "module",
@@ -67,12 +67,14 @@
     "@codemirror/view": "^6.40.0",
     "@lezer/highlight": "^1.0.0",
     "date-fns": "^4.1.0",
+    "echarts": "^5.5.0",
     "ol": "^10.0.0",
     "svelte": "^5.0.0"
   },
   "devDependencies": {
     "@sveltejs/package": "^2.5.7",
     "date-fns": "^4.1.0",
+    "echarts": "^5.6.0",
     "ol": "^10.8.0",
     "svelte": "^5.55.3",
     "svelte-check": "^4.4.6",