@aiaiai-pt/design-system 0.38.0 → 0.39.0

package/components/DateRangePicker.svelte.d.ts

@@ -35,7 +35,7 @@ declare const DateRangePicker: import("svelte").Component<{
     onchange?: any;
     id?: any;
     class?: string;
-} & Record<string, any>, {}, "end" | "start">;
+} & Record<string, any>, {}, "start" | "end">;
 type $$ComponentProps = {
     start?: any;
     end?: any;

package/components/EChart.svelte

@@ -1,64 +1,81 @@
 <!--
   @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.
+  A categorical chart over a public aggregate VIEW, 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.
+
+  Declarative + multi-series (#176 follow-on): the data contract is the
+  column-aligned `{ category, series[] }` (`ChartData`) produced by `toSeriesData`
+  — a single series is the degenerate case, ≥2 series is multi-series. Each series
+  carries its own `type` (bar/line/area/scatter/pie), optional `stack`, and
+  optional secondary `axis`; the ECharts `option` is built by the PURE
+  `buildChartOption` (unit-tested separately). Back-compat: the legacy
+  `items={[{label,value}]}` + `kind` props synthesise a single series.
+
+  ECharts is LAZY-loaded 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.
+
+  Themed from the live `--color-*` semantic tokens read off the container, and
+  re-themed on `data-theme` / `prefers-color-scheme` change (#244). The per-series
+  palette is an alpha ramp off `--color-accent` — no hardcoded colour list.
+  Soft-empty: no series/category → 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 },
+    caption="Reports by status"
+    labelHeader="Status"
+    category={["Open", "In progress", "Resolved"]}
+    series={[
+      { name: "Open", type: "bar", data: [12, 0, 0] },
+      { name: "Resolved", type: "bar", data: [0, 0, 31] },
     ]}
+    legend
     locale="pt"
   />
 -->
 <script module>
   /**
    * @typedef {{ label: string, value: number }} ChartItem
+   * @typedef {import('./renderer/aggregate').ChartData} ChartData
+   * @typedef {import('./renderer/aggregate').SeriesData} SeriesData
    */
 </script>
 
 <script>
   import { watchTheme } from "./map-utils.js";
+  import { buildChartOption } from "./renderer/chart-option";
 
   let {
-    /** @type {ChartItem[]} The categorical rows to plot. */
+    /** @type {string[]} The category (x / pie-angle) ticks. */
+    category = [],
+    /** @type {SeriesData[]} The series to plot (≥1; ≥2 = multi-series). */
+    series = [],
+    /** @type {boolean} Render a legend (needed once there are ≥2 series). */
+    legend = false,
+    /** @type {"horizontal" | "vertical" | undefined} Cartesian orientation. */
+    orientation = undefined,
+    /** @type {boolean} Enable a 2nd value axis for `axis: "secondary"` series. */
+    ySecondary = false,
+    /** @type {number} Pie/donut hole as a fraction of the radius (0 = full pie). */
+    innerRadius = 0,
+    /** @type {ChartItem[]} BACK-COMPAT: single-series `{label,value}` rows. */
     items = [],
+    /** @type {"bar" | "line" | "donut"} BACK-COMPAT: legacy single-series kind. */
+    kind = "bar",
     /** @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). */
+    /** @type {string} Header for the (legacy single) value column (localize it). */
     valueHeader = "Value",
     /** @type {string} BCP-47 locale for number formatting. */
     locale = "en",
-    /** @type {"bar" | "line" | "donut"} Chart kind (#176 Tier 1). `bar` is the
-     * horizontal categorical bar; `line` plots the same series as a value line
-     * over the category axis; `donut` is a ring pie. The data table below is
-     * the accessible source of truth for every kind. */
-    kind = "bar",
     /** @type {string} CSS block-size for the chart canvas. */
     height = "20rem",
     /** @type {string} */
@@ -71,17 +88,49 @@
     return new Intl.NumberFormat(locale).format(value);
   }
 
+  // Normalise to the declarative `{ category, series }` contract. When `series`
+  // is given we render it directly; otherwise we synthesise a single series from
+  // the legacy `items` + `kind` (donut → a pie series).
+  /** @type {ChartData} */
+  const chartData = $derived.by(() => {
+    if (series.length > 0) return { category, series };
+    if (items.length === 0) return { category: [], series: [] };
+    const t = kind === "donut" ? "pie" : kind;
+    return {
+      category: items.map((it) => it.label),
+      series: [
+        {
+          name: valueHeader,
+          type: /** @type {SeriesData["type"]} */ (t),
+          data: items.map((it) => it.value),
+        },
+      ],
+    };
+  });
+
+  // Legacy donut gets the ring hole even though the caller passes no innerRadius.
+  const effInnerRadius = $derived(
+    series.length === 0 && kind === "donut" ? 0.45 : innerRadius,
+  );
+
+  // The legacy single-series `kind="bar"` rendered a HORIZONTAL bar (category on
+  // the y-axis). Preserve that look for back-compat callers; the declarative
+  // path defaults to vertical (category on x) unless `orientation` says otherwise.
+  const effOrientation = $derived(
+    orientation ?? (series.length === 0 && kind === "bar" ? "horizontal" : undefined),
+  );
+
+  const hasData = $derived(
+    chartData.series.length > 0 && chartData.category.length > 0,
+  );
+
   /** @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. */
+  /** Build the ECharts option from current data + the container's tokens. */
   function buildOption() {
     const el = container;
     if (!el) return {};
@@ -90,110 +139,19 @@
       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");
-
-    // Donut: a ring pie. No axes; the slice palette derives from the accent
-    // (alpha ramp) so it stays on-theme without a hardcoded colour list.
-    if (kind === "donut") {
-      const palette = items.map((_, i) => {
-        const alpha = Math.max(0.35, 1 - i * 0.12);
-        return `color-mix(in srgb, ${accent} ${Math.round(alpha * 100)}%, transparent)`;
-      });
-      return {
-        animation: false,
-        tooltip: {
-          trigger: "item",
-          /** @param {{ name: string, value: number, percent: number }} p */
-          formatter: (p) => `${p.name}: ${fmt(p.value)} (${p.percent}%)`,
-        },
-        color: palette,
-        series: [
-          {
-            type: "pie",
-            radius: ["45%", "72%"],
-            data: items.map((it) => ({ name: it.label, value: it.value })),
-            label: { color: textPrimary },
-            labelLine: { lineStyle: { color: border } },
-          },
-        ],
-      };
-    }
-
-    // Line: value over the category axis, in the consumer's order (desc by
-    // value). Shares the same accent + token theming as the bar.
-    if (kind === "line") {
-      return {
-        animation: false,
-        grid: { left: 8, right: 16, top: 8, bottom: 8, containLabel: true },
-        tooltip: {
-          trigger: "axis",
-          /** @param {{ name: string, value: number }[]} p */
-          formatter: (p) => `${p[0]?.name}: ${fmt(p[0]?.value)}`,
-        },
-        xAxis: {
-          type: "category",
-          data: items.map((it) => it.label),
-          axisLabel: { color: textPrimary },
-          axisLine: { lineStyle: { color: border } },
-          axisTick: { show: false },
-        },
-        yAxis: {
-          type: "value",
-          axisLabel: { color: textSecondary, formatter: (/** @type {number} */ v) => fmt(v) },
-          axisLine: { lineStyle: { color: border } },
-          splitLine: { lineStyle: { color: border } },
-        },
-        series: [
-          {
-            type: "line",
-            data: items.map((it) => it.value),
-            itemStyle: { color: accent },
-            lineStyle: { color: accent },
-            symbolSize: 7,
-            smooth: false,
-          },
-        ],
-      };
-    }
-
-    // Bar (default). 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 } },
+    return buildChartOption(chartData, {
+      tokens: {
+        accent: token("--color-accent", "#2563eb"),
+        textPrimary: token("--color-text-primary", "#1f2937"),
+        textSecondary: token("--color-text-secondary", "#6b7280"),
+        border: token("--color-border", "#e5e7eb"),
       },
-      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,
-        },
-      ],
-    };
+      locale,
+      legend,
+      orientation: effOrientation,
+      ySecondary,
+      innerRadius: effInnerRadius,
+    });
   }
 
   $effect(() => {
@@ -221,8 +179,10 @@
           charts.BarChart,
           charts.LineChart,
           charts.PieChart,
+          charts.ScatterChart,
           components.GridComponent,
           components.TooltipComponent,
+          components.LegendComponent,
           renderers.CanvasRenderer,
         ]);
 
@@ -233,7 +193,7 @@
         ro = new ResizeObserver(() => chart?.resize());
         ro.observe(container);
 
-        disposeTheme = watchTheme(() => chart?.setOption(buildOption()));
+        disposeTheme = watchTheme(() => chart?.setOption(buildOption(), true));
       } 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.
@@ -251,21 +211,21 @@
     };
   });
 
-  // 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.
+  // Re-apply the option when the data / locale / options change after mount (the
+  // canvas persists; only the option is swapped). `true` replaces (not merges)
+  // so stale axis/series components from a previous shape are cleared.
   $effect(() => {
-    // touch reactive deps so the effect re-runs when they change
-    void items;
+    void chartData;
     void locale;
-    void kind;
-    // A kind switch changes which axes/series exist; replace (not merge) the
-    // option so stale axis components from the previous kind are cleared.
+    void legend;
+    void effOrientation;
+    void ySecondary;
+    void effInnerRadius;
     if (_chart) _chart.setOption(buildOption(), true);
   });
 </script>
 
-{#if items.length > 0}
+{#if hasData}
   <figure class="echart {className}" aria-label={caption} {...rest}>
     <!-- Decorative visual: the data lives in the table below. -->
     <div
@@ -275,21 +235,26 @@
       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). -->
+    <!-- Accessible source of truth — always rendered (ARTE #3/#6), one value
+         column per series. 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>
+          {#each chartData.series as s (s.name)}
+            <th scope="col">{s.name}</th>
+          {/each}
         </tr>
       </thead>
       <tbody>
-        {#each items as item, i (item.label + i)}
+        {#each chartData.category as cat, r (cat + r)}
           <tr>
-            <th scope="row">{item.label}</th>
-            <td>{fmt(item.value)}</td>
+            <th scope="row">{cat}</th>
+            {#each chartData.series as s (s.name)}
+              <td>{fmt(s.data[r] ?? 0)}</td>
+            {/each}
           </tr>
         {/each}
       </tbody>

package/components/EChart.svelte.d.ts

@@ -3,6 +3,8 @@ export type ChartItem = {
     label: string;
     value: number;
 };
+export type ChartData = import("./renderer/aggregate").ChartData;
+export type SeriesData = import("./renderer/aggregate").SeriesData;
 type EChart = {
     $on?(type: string, callback: (e: any) => void): () => void;
     $set?(props: Partial<$$ComponentProps>): void;
@@ -10,41 +12,53 @@ type EChart = {
 /**
  * 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.
+ * A categorical chart over a public aggregate VIEW, 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.
+ * Declarative + multi-series (#176 follow-on): the data contract is the
+ * column-aligned `{ category, series[] }` (`ChartData`) produced by `toSeriesData`
+ * — a single series is the degenerate case, ≥2 series is multi-series. Each series
+ * carries its own `type` (bar/line/area/scatter/pie), optional `stack`, and
+ * optional secondary `axis`; the ECharts `option` is built by the PURE
+ * `buildChartOption` (unit-tested separately). Back-compat: the legacy
+ * `items={[{label,value}]}` + `kind` props synthesise a single series.
  *
- * 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.
+ * ECharts is LAZY-loaded 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.
+ *
+ * Themed from the live `--color-*` semantic tokens read off the container, and
+ * re-themed on `data-theme` / `prefers-color-scheme` change (#244). The per-series
+ * palette is an alpha ramp off `--color-accent` — no hardcoded colour list.
+ * Soft-empty: no series/category → 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 },
+ *   caption="Reports by status"
+ *   labelHeader="Status"
+ *   category={["Open", "In progress", "Resolved"]}
+ *   series={[
+ *     { name: "Open", type: "bar", data: [12, 0, 0] },
+ *     { name: "Resolved", type: "bar", data: [0, 0, 31] },
  *   ]}
+ *   legend
  *   locale="pt"
  * />
  */
 declare const EChart: import("svelte").Component<{
+    category?: any[];
+    series?: any[];
+    legend?: boolean;
+    orientation?: any;
+    ySecondary?: boolean;
+    innerRadius?: number;
     items?: any[];
+    kind?: string;
     caption?: string;
     labelHeader?: string;
     valueHeader?: string;
@@ -53,7 +67,14 @@ declare const EChart: import("svelte").Component<{
     class?: string;
 } & Record<string, any>, {}, "">;
 type $$ComponentProps = {
+    category?: any[];
+    series?: any[];
+    legend?: boolean;
+    orientation?: any;
+    ySecondary?: boolean;
+    innerRadius?: number;
     items?: any[];
+    kind?: string;
     caption?: string;
     labelHeader?: string;
     valueHeader?: string;

package/components/NotificationPrefs.svelte.d.ts

@@ -4,6 +4,7 @@ export type PrefItem = {
     label: string;
     description?: string;
     active: boolean;
+    group?: string;
 };
 type NotificationPrefs = {
     $on?(type: string, callback: (e: any) => void): () => void;
@@ -19,16 +20,18 @@ type NotificationPrefs = {
  * Toggling a row calls `onToggle(id, next)` — the consumer performs the write
  * and re-feeds `items` (or sets `busyId` while it's in flight).
  *
- * Accessibility-first: a bordered semantic list; each row pairs a real text
- * label (and optional description) with a `Toggle` (`role="switch"`,
- * `aria-checked`). The switch carries an accessible name via `aria-label` so the
- * control reads on its own. A row that's saving is `disabled` (no double-submit).
- * Consumes semantic tokens so dark / high-contrast schemes (#244) ride through.
- * Soft-empty: no items → renders the `emptyText` note (never an empty shell).
+ * Accessibility-first: a bordered semantic list inside a `<section>` region
+ * named by `label` (the visible page heading is the consumer's job — same split
+ * as RankingBoard, so one widget can own the page `<h1>`). Each row pairs a real
+ * text label (and optional description) with a `Toggle` (`role="switch"`,
+ * `aria-checked`); the switch carries its own accessible name via `aria-label`.
+ * A row that's saving is `disabled` (no double-submit). Consumes semantic tokens
+ * so dark / high-contrast schemes (#244) ride through. Soft-empty: no items →
+ * renders the `emptyText` note (never an empty shell).
  *
  * @example
  * <NotificationPrefs
- *   heading="Notifications"
+ *   label="Notifications"
  *   items={[
  *     { id: "all", label: "All updates", description: "Every proposal and phase change", active: true },
  *     { id: "sub-2", label: "Cycling lane", active: false },
@@ -39,7 +42,7 @@ type NotificationPrefs = {
  */
 declare const NotificationPrefs: import("svelte").Component<{
     items?: any[];
-    heading?: string;
+    label?: string;
     emptyText?: string;
     onToggle?: any;
     busyId?: any;
@@ -47,7 +50,7 @@ declare const NotificationPrefs: import("svelte").Component<{
 } & Record<string, any>, {}, "">;
 type $$ComponentProps = {
     items?: any[];
-    heading?: string;
+    label?: string;
     emptyText?: string;
     onToggle?: any;
     busyId?: any;