@aiaiai-pt/design-system 0.34.0 → 0.36.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/display.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Host-agnostic display transforms (#499 criterion A) — the pure value→text +
+ * status-badge + geo helpers the list/detail surfaces of BOTH hosts (the
+ * citizen portal AND the staff admin) share. Previously duplicated: the portal
+ * kept them in `portal/src/lib/renderer/{cells,columns}.ts`; the admin re-rolled
+ * equivalents inline (`renderCell`/`formatValue`). Lifting them here makes the
+ * value-redaction boundary one tested function instead of two drifting ones.
+ *
+ * Two host forks are parameters, not separate copies (the reconciliation #499
+ * called out before sharing):
+ *   - object fallback: the portal REDACTS an unknown object (never leak a blob
+ *     into the public DOM — a hard rule); the admin JSON-dumps it for operators.
+ *     → `formatScalar(value, { objectFallback: "redact" | "json" })`, default
+ *     "redact" (the safe default; a caller opts INTO dumping).
+ *   - date detection: the portal detects timestamps by VALUE shape (the public
+ *     schema strips created_at/updated_at, so type-driven detection misses
+ *     them); the admin knows the field is a datetime from its schema TYPE.
+ *     → `displayCell(value, locale, { treatAsDate })` — `treatAsDate` forces
+ *     date formatting (admin, from schema type); otherwise value-shape
+ *     detection (`isIsoTimestamp`) applies (portal).
+ *
+ * Everything here is PURE and dependency-free.
+ */
+export type ObjectFallback = "redact" | "json";
+/**
+ * Pure value → display string. Scalars stringify; arrays join their non-empty
+ * formatted members; a disclosed relationship object ({id,label}|{name}|{title})
+ * renders its human label then its id. An UNKNOWN object renders per
+ * `objectFallback`: "redact" (default) → "" (never dumps internals — the public
+ * security boundary); "json" → pretty JSON (the admin operator view).
+ */
+export declare function formatScalar(value: unknown, opts?: {
+    objectFallback?: ObjectFallback;
+}): string;
+/** True for an ISO-8601 timestamp STRING (not a bare date). Value-shape
+ *  detection — used where the schema can't tell us the field is a datetime. */
+export declare function isIsoTimestamp(value: unknown): value is string;
+/** Locale date for an ISO timestamp (date-only, UTC-stable so SSR == hydrate);
+ *  the raw string when unparseable. */
+export declare function formatTimestamp(value: string, locale: string): string;
+/**
+ * The single display boundary for list cells / detail values. Formats a value
+ * as a locale date when it's a timestamp — either because `opts.treatAsDate`
+ * forces it (the admin, from the schema field type) or because the value itself
+ * looks like an ISO timestamp (the portal, value-shape). Everything else goes
+ * through `formatScalar` (with the host's object-fallback policy).
+ */
+export declare function displayCell(value: unknown, locale: string, opts?: {
+    treatAsDate?: boolean;
+    objectFallback?: ObjectFallback;
+}): string;
+/** Operator copy for a status value (falls back to the raw value). `labels` is
+ *  untrusted DATA — a non-object/array is ignored. */
+export declare function statusLabel(value: unknown, labels: unknown): string;
+/** DS Badge variant for a status value (neutral when unmapped). `variants` is
+ *  untrusted DATA — a non-object/array is ignored. */
+export declare function statusVariant(value: unknown, variants: unknown): string;
+/** Resolve a status value to a `{ label, variant }` pair in one call. */
+export declare function resolveStatusBadge(value: unknown, opts?: {
+    labels?: unknown;
+    variants?: unknown;
+}): {
+    label: string;
+    variant: string;
+};
+/**
+ * Extract a `[lon, lat]` pair from a GeoJSON-ish Point value (the shape both a
+ * detail row's location FK and a MapPicker value use), or null when it isn't a
+ * usable point. Pure — the map widget decides how to render the result.
+ */
+export declare function geoPoint(value: unknown): [number, number] | null;

package/components/renderer/display.ts

@@ -0,0 +1,161 @@
+/**
+ * Host-agnostic display transforms (#499 criterion A) — the pure value→text +
+ * status-badge + geo helpers the list/detail surfaces of BOTH hosts (the
+ * citizen portal AND the staff admin) share. Previously duplicated: the portal
+ * kept them in `portal/src/lib/renderer/{cells,columns}.ts`; the admin re-rolled
+ * equivalents inline (`renderCell`/`formatValue`). Lifting them here makes the
+ * value-redaction boundary one tested function instead of two drifting ones.
+ *
+ * Two host forks are parameters, not separate copies (the reconciliation #499
+ * called out before sharing):
+ *   - object fallback: the portal REDACTS an unknown object (never leak a blob
+ *     into the public DOM — a hard rule); the admin JSON-dumps it for operators.
+ *     → `formatScalar(value, { objectFallback: "redact" | "json" })`, default
+ *     "redact" (the safe default; a caller opts INTO dumping).
+ *   - date detection: the portal detects timestamps by VALUE shape (the public
+ *     schema strips created_at/updated_at, so type-driven detection misses
+ *     them); the admin knows the field is a datetime from its schema TYPE.
+ *     → `displayCell(value, locale, { treatAsDate })` — `treatAsDate` forces
+ *     date formatting (admin, from schema type); otherwise value-shape
+ *     detection (`isIsoTimestamp`) applies (portal).
+ *
+ * Everything here is PURE and dependency-free.
+ */
+
+export type ObjectFallback = "redact" | "json";
+
+/**
+ * Pure value → display string. Scalars stringify; arrays join their non-empty
+ * formatted members; a disclosed relationship object ({id,label}|{name}|{title})
+ * renders its human label then its id. An UNKNOWN object renders per
+ * `objectFallback`: "redact" (default) → "" (never dumps internals — the public
+ * security boundary); "json" → pretty JSON (the admin operator view).
+ */
+export function formatScalar(
+  value: unknown,
+  opts: { objectFallback?: ObjectFallback } = {},
+): string {
+  // `== null` catches both null and undefined.
+  if (value == null) return "";
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  if (Array.isArray(value)) {
+    return value
+      .map((v) => formatScalar(v, opts))
+      .filter(Boolean)
+      .join(", ");
+  }
+  if (typeof value === "object") {
+    const o = value as Record<string, unknown>;
+    for (const k of ["label", "name", "title"]) {
+      const v = o[k];
+      if (typeof v === "string" && v) return v;
+    }
+    const id = o.id;
+    if (typeof id === "string" || typeof id === "number") return String(id);
+    // No human handle and no id → fall back per host policy.
+    if (opts.objectFallback === "json") {
+      try {
+        return JSON.stringify(value, null, 2);
+      } catch {
+        return "";
+      }
+    }
+    return "";
+  }
+  return "";
+}
+
+const ISO_TIMESTAMP_RE =
+  /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})$/;
+
+/** True for an ISO-8601 timestamp STRING (not a bare date). Value-shape
+ *  detection — used where the schema can't tell us the field is a datetime. */
+export function isIsoTimestamp(value: unknown): value is string {
+  return typeof value === "string" && ISO_TIMESTAMP_RE.test(value);
+}
+
+/** Locale date for an ISO timestamp (date-only, UTC-stable so SSR == hydrate);
+ *  the raw string when unparseable. */
+export function formatTimestamp(value: string, locale: string): string {
+  const parsed = new Date(value);
+  if (Number.isNaN(parsed.getTime())) return value;
+  try {
+    return new Intl.DateTimeFormat(locale || "en", {
+      dateStyle: "medium",
+      timeZone: "UTC",
+    }).format(parsed);
+  } catch {
+    return value;
+  }
+}
+
+/**
+ * The single display boundary for list cells / detail values. Formats a value
+ * as a locale date when it's a timestamp — either because `opts.treatAsDate`
+ * forces it (the admin, from the schema field type) or because the value itself
+ * looks like an ISO timestamp (the portal, value-shape). Everything else goes
+ * through `formatScalar` (with the host's object-fallback policy).
+ */
+export function displayCell(
+  value: unknown,
+  locale: string,
+  opts: { treatAsDate?: boolean; objectFallback?: ObjectFallback } = {},
+): string {
+  if (opts.treatAsDate && typeof value === "string" && value) {
+    return formatTimestamp(value, locale);
+  }
+  if (isIsoTimestamp(value)) return formatTimestamp(value, locale);
+  return formatScalar(value, { objectFallback: opts.objectFallback });
+}
+
+/** Operator copy for a status value (falls back to the raw value). `labels` is
+ *  untrusted DATA — a non-object/array is ignored. */
+export function statusLabel(value: unknown, labels: unknown): string {
+  const raw = formatScalar(value);
+  if (labels && typeof labels === "object" && !Array.isArray(labels)) {
+    const mapped = (labels as Record<string, unknown>)[raw];
+    if (typeof mapped === "string" && mapped) return mapped;
+  }
+  return raw;
+}
+
+/** DS Badge variant for a status value (neutral when unmapped). `variants` is
+ *  untrusted DATA — a non-object/array is ignored. */
+export function statusVariant(value: unknown, variants: unknown): string {
+  const raw = formatScalar(value);
+  if (variants && typeof variants === "object" && !Array.isArray(variants)) {
+    const mapped = (variants as Record<string, unknown>)[raw];
+    if (typeof mapped === "string" && mapped) return mapped;
+  }
+  return "neutral";
+}
+
+/** Resolve a status value to a `{ label, variant }` pair in one call. */
+export function resolveStatusBadge(
+  value: unknown,
+  opts: { labels?: unknown; variants?: unknown } = {},
+): { label: string; variant: string } {
+  return {
+    label: statusLabel(value, opts.labels),
+    variant: statusVariant(value, opts.variants),
+  };
+}
+
+/**
+ * Extract a `[lon, lat]` pair from a GeoJSON-ish Point value (the shape both a
+ * detail row's location FK and a MapPicker value use), or null when it isn't a
+ * usable point. Pure — the map widget decides how to render the result.
+ */
+export function geoPoint(value: unknown): [number, number] | null {
+  if (!value || typeof value !== "object") return null;
+  const coords = (value as { coordinates?: unknown }).coordinates;
+  if (!Array.isArray(coords) || coords.length < 2) return null;
+  const lon = coords[0];
+  const lat = coords[1];
+  if (typeof lon !== "number" || typeof lat !== "number") return null;
+  if (!Number.isFinite(lon) || !Number.isFinite(lat)) return null;
+  return [lon, lat];
+}

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.36.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",