@aiaiai-pt/design-system 0.38.1 → 0.40.0

package/components/ResultsChart.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 ResultsChart = {
     $on?(type: string, callback: (e: any) => void): () => void;
     $set?(props: Partial<$$ComponentProps>): void;
@@ -10,32 +12,35 @@ type ResultsChart = {
 /**
  * ResultsChart
  *
- * A horizontal bar chart for a single categorical aggregate (votes per proposal,
- * reports per category, consumption per meter) that SHIPS ITS DATA TABLE. The
- * visual bars are decorative (`aria-hidden`); the accompanying `<table>` is the
- * accessible source of truth, always rendered — so the data is reachable with 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 dependency-free (pure-CSS) categorical chart that SHIPS ITS DATA TABLE — the
+ * SSR / no-JS fallback sibling of `EChart`. The visual bars are decorative
+ * (`aria-hidden`); the accompanying `<table>` is the accessible source of truth,
+ * always rendered — so the data is reachable with 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): consumes the same column-aligned
+ * `{ category, series[] }` (`ChartData`) as `EChart`. The data TABLE renders one
+ * value column per series (full fidelity, no JS); the CSS bars render the FIRST
+ * series only (a simple horizontal bar is the honest no-JS visual — stacked /
+ * dual-axis geometry needs the canvas). Back-compat: legacy `items={[{label,
+ * value}]}` synthesises a single series.
  *
- * Vertical-agnostic: `items` is already shaped to `{ label, value }`; the consumer
- * (a portal widget over a public aggregate VIEW) maps the view columns and orders
- * the rows. Dependency-free (pure CSS bars) so it stays a11y- and SSR-clean.
  * Consumes semantic tokens so dark / high-contrast schemes (#244) ride through.
- * Soft-empty: no items → renders nothing.
+ * Soft-empty: no series/category → renders nothing.
  *
  * @example
  * <ResultsChart
  *   caption="Votes per proposal"
  *   labelHeader="Proposal"
- *   valueHeader="Votes"
- *   items={[
- *     { label: "Ciclovia da Marginal", value: 1284 },
- *     { label: "Parque infantil de Gaia", value: 967 },
- *   ]}
+ *   category={["Ciclovia", "Parque"]}
+ *   series={[{ name: "Votes", type: "bar", data: [1284, 967] }]}
  *   locale="pt"
  * />
  */
 declare const ResultsChart: import("svelte").Component<{
+    category?: any[];
+    series?: any[];
     items?: any[];
     caption?: string;
     labelHeader?: string;
@@ -44,6 +49,8 @@ declare const ResultsChart: import("svelte").Component<{
     class?: string;
 } & Record<string, any>, {}, "">;
 type $$ComponentProps = {
+    category?: any[];
+    series?: any[];
     items?: any[];
     caption?: string;
     labelHeader?: string;

package/components/renderer/EChartWidget.svelte

@@ -1,19 +1,22 @@
 <script lang="ts">
   import EChart from "../EChart.svelte";
   import type { WidgetProps } from "./types";
-  import { toRankedItems } from "./aggregate";
+  import { toRankedItems, toSeriesData, type ChartSpec } from "./aggregate";
+  import { asChartSpec } from "./chart-spec";
 
-  // `chart` widget (#498) — an ECharts bar chart over a public aggregate VIEW,
+  // `chart` / `echart` widget — an ECharts 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.
-  // `kind` is bound by the registry wrapper (line-chart / donut-chart), NOT by
-  // the dispatcher (which renders this widget with the standard WidgetProps and
-  // no kind → the `chart` key stays the ECharts bar). #176 Tier 1.
+  // `kind: "aggregate"`. 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; NO resolve-data / provider
+  // change needed.
+  //
+  // Two authoring modes (#176 follow-on):
+  //  • DECLARATIVE — `props.chart_spec` (category column + ≥1 series of value
+  //    columns, each with its own type/stack/axis + chart options). Projected
+  //    via `toSeriesData`; multi-series is the ≥2-series case.
+  //  • LEGACY — `props.label_field` / `value_field` (+ registry `kind`). A single
+  //    series via `toRankedItems`. Kept for back-compat reads.
   let { data, props, ownsH1, locale, kind = "bar" }: WidgetProps & {
     kind?: "bar" | "line" | "donut";
   } = $props();
@@ -24,6 +27,11 @@
       : [],
   );
 
+  // Declarative spec (validated/whitelisted) — null when the block is legacy.
+  const spec = $derived<ChartSpec | null>(asChartSpec(props.chart_spec));
+  const chartData = $derived(spec ? toSeriesData(rows, spec) : null);
+
+  // Legacy single-series projection (only used when there is no spec).
   const labelField = $derived(
     typeof props.label_field === "string" && props.label_field
       ? props.label_field
@@ -37,9 +45,12 @@
   const limit = $derived(
     typeof props.limit === "number" && props.limit > 0 ? props.limit : 0,
   );
+  const legacyItems = $derived(
+    spec ? [] : toRankedItems(rows, { labelField, valueField, limit }),
+  );
 
-  const items = $derived(
-    toRankedItems(rows, { labelField, valueField, limit }),
+  const hasData = $derived(
+    chartData ? chartData.series.length > 0 && chartData.category.length > 0 : legacyItems.length > 0,
   );
 
   const heading = $derived(
@@ -58,19 +69,33 @@
   );
 </script>
 
-{#if items.length > 0}
+{#if hasData}
   <section class="widget-band">
     {#if heading}
       {#if ownsH1}<h1>{heading}</h1>{:else}<h2>{heading}</h2>{/if}
     {/if}
-    <EChart
-      {items}
-      {caption}
-      {labelHeader}
-      {valueHeader}
-      {kind}
-      locale={locale ?? "en"}
-    />
+    {#if chartData}
+      <EChart
+        category={chartData.category}
+        series={chartData.series}
+        legend={spec?.options?.legend ?? (chartData.series.length > 1)}
+        orientation={spec?.options?.orientation}
+        ySecondary={spec?.options?.y_secondary ?? false}
+        innerRadius={spec?.options?.inner_radius ?? 0}
+        {caption}
+        {labelHeader}
+        locale={locale ?? "en"}
+      />
+    {:else}
+      <EChart
+        items={legacyItems}
+        {caption}
+        {labelHeader}
+        {valueHeader}
+        {kind}
+        locale={locale ?? "en"}
+      />
+    {/if}
   </section>
 {/if}
 

package/components/renderer/ResultsChartWidget.svelte

@@ -1,15 +1,16 @@
 <script lang="ts">
   import ResultsChart from "../ResultsChart.svelte";
   import type { WidgetProps } from "./types";
-  import { toRankedItems } from "./aggregate";
+  import { toRankedItems, toSeriesData, type ChartSpec } from "./aggregate";
+  import { asChartSpec } from "./chart-spec";
 
-  // `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.
+  // `results-chart` widget (#105 Phase 4) — the dependency-free (pure-CSS) SSR /
+  // no-JS fallback 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"`. Same two authoring modes as EChartWidget (#176 follow-on):
+  //  • DECLARATIVE — `props.chart_spec` projected via `toSeriesData`; the table
+  //    renders ALL series, the CSS bars render the first.
+  //  • LEGACY — `props.label_field` / `value_field` via `toRankedItems`.
   let { data, props, ownsH1, locale }: WidgetProps = $props();
 
   const rows = $derived(
@@ -18,6 +19,9 @@
       : [],
   );
 
+  const spec = $derived<ChartSpec | null>(asChartSpec(props.chart_spec));
+  const chartData = $derived(spec ? toSeriesData(rows, spec) : null);
+
   const labelField = $derived(
     typeof props.label_field === "string" && props.label_field
       ? props.label_field
@@ -31,9 +35,12 @@
   const limit = $derived(
     typeof props.limit === "number" && props.limit > 0 ? props.limit : 0,
   );
+  const legacyItems = $derived(
+    spec ? [] : toRankedItems(rows, { labelField, valueField, limit }),
+  );
 
-  const items = $derived(
-    toRankedItems(rows, { labelField, valueField, limit }),
+  const hasData = $derived(
+    chartData ? chartData.series.length > 0 && chartData.category.length > 0 : legacyItems.length > 0,
   );
 
   const heading = $derived(
@@ -52,18 +59,28 @@
   );
 </script>
 
-{#if items.length > 0}
+{#if hasData}
   <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"}
-    />
+    {#if chartData}
+      <ResultsChart
+        category={chartData.category}
+        series={chartData.series}
+        {caption}
+        {labelHeader}
+        locale={locale ?? "en"}
+      />
+    {:else}
+      <ResultsChart
+        items={legacyItems}
+        {caption}
+        {labelHeader}
+        {valueHeader}
+        locale={locale ?? "en"}
+      />
+    {/if}
   </section>
 {/if}
 

package/components/renderer/aggregate.d.ts

@@ -32,3 +32,66 @@ export interface ToRankedOptions {
  * (ties keep input order); rows are never mutated.
  */
 export declare function toRankedItems(rows: ReadonlyArray<Record<string, unknown>>, opts?: ToRankedOptions): RankedItem[];
+/** The curated series render kinds (whitelist; unknown → dropped upstream). */
+export type ChartSeriesType = "bar" | "line" | "area" | "scatter" | "pie";
+/** One series: a view value column rendered as `type`. */
+export interface ChartSeriesSpec {
+    /** View output (value) column this series plots. */
+    column: string;
+    /** Render geometry for this series. */
+    type: ChartSeriesType;
+    /** Legend / table header label. Defaults to `column`. */
+    name?: string;
+    /** Bars/areas sharing a `stack` id are stacked together. */
+    stack?: string;
+    /** `secondary` pins the series to the 2nd value axis (dual-axis). */
+    axis?: "primary" | "secondary";
+}
+/** Chart-level enumerated options (no strings that become code). */
+export interface ChartOptions {
+    /** Render a legend (needed once there are ≥2 series). */
+    legend?: boolean;
+    /** Cartesian orientation: `vertical` = category on x (default). */
+    orientation?: "horizontal" | "vertical";
+    /** Enable a 2nd value axis for `axis: "secondary"` series. */
+    y_secondary?: boolean;
+    /** Pie/donut hole as a fraction of the outer radius (0 = full pie). */
+    inner_radius?: number;
+}
+/** The declarative chart spec carried on a chart block's props. */
+export interface ChartSpec {
+    /** Aggregate VIEW code (also lives on the block binding/entity). */
+    view_code?: string;
+    /** The category (x / pie-angle) column. */
+    category: {
+        column: string;
+    };
+    /** ≥1 series; ≥2 = multi-series. */
+    series: ChartSeriesSpec[];
+    options?: ChartOptions;
+    /** Defensive client-side row cap (server `?limit=` is authoritative). */
+    limit?: number;
+    /** Echoes the binding order term (for reference; ordering is server-side). */
+    order_by?: string;
+}
+/** A column-aligned series ready for the renderer. */
+export interface SeriesData {
+    name: string;
+    type: ChartSeriesType;
+    data: number[];
+    stack?: string;
+    axis?: "primary" | "secondary";
+}
+/** The shape `EChart` / `ResultsChart` render: aligned category + series. */
+export interface ChartData {
+    category: string[];
+    series: SeriesData[];
+}
+/**
+ * Project resolved VIEW rows → `{ category, series[] }` per a `ChartSpec`.
+ * Pure: rows are never mutated and never re-sorted (order is the binding's
+ * job). Blank-category rows are dropped (they have no axis tick) — dropping a
+ * row removes that index from EVERY series so the columns stay aligned. A
+ * non-numeric cell coerces to 0 (fail-soft, same as `toRankedItems`).
+ */
+export declare function toSeriesData(rows: ReadonlyArray<Record<string, unknown>>, spec: ChartSpec): ChartData;

package/components/renderer/aggregate.ts

@@ -70,3 +70,126 @@ export function toRankedItems(
     ? sorted.slice(0, Math.floor(opts.limit))
     : sorted;
 }
+
+/*
+ * ────────────────────────────────────────────────────────────────────────────
+ * Declarative multi-series chart spec (#176 follow-on) — PURE, JSON-only.
+ *
+ * The single-series `{label,value}` projection above is the degenerate "one
+ * series" case. The declarative model binds a chart block to a public aggregate
+ * VIEW and a set of OUTPUT COLUMNS: one `category` column (the x / pie-angle
+ * axis) and ≥1 `series`, each naming a value column + a render `type`. Multi-
+ * series is then just "≥2 series", not a bespoke feature.
+ *
+ * Three load-bearing constraints (see dev_docs/specs/176-declarative-chart-
+ * authoring.md): (1) JSON-ONLY — no operator-authored functions ever reach the
+ * runtime (TH-08); the DS supplies all behaviours. (2) BIND COLUMNS, not data —
+ * a series references a view output column, resolved at render via the existing
+ * DataProvider. (3) CURATED WHITELIST — every `type`/`option` is an enum/number/
+ * boolean; unknown keys are ignored, never passed through.
+ *
+ * `toSeriesData` is the multi-series analogue of `toRankedItems`: it maps the
+ * resolved VIEW rows into the column-aligned `{ category, series[] }` the DS
+ * `EChart` renders. Row ORDER and the row CAP are the binding's job (forwarded
+ * to the BFF as `?order_by=` / `?limit=`, applied server-side); this shaper is a
+ * pure column projection over the rows it is handed — it never re-sorts. A
+ * `limit` here is honoured only as a defensive client-side cap.
+ */
+
+/** The curated series render kinds (whitelist; unknown → dropped upstream). */
+export type ChartSeriesType = "bar" | "line" | "area" | "scatter" | "pie";
+
+/** One series: a view value column rendered as `type`. */
+export interface ChartSeriesSpec {
+  /** View output (value) column this series plots. */
+  column: string;
+  /** Render geometry for this series. */
+  type: ChartSeriesType;
+  /** Legend / table header label. Defaults to `column`. */
+  name?: string;
+  /** Bars/areas sharing a `stack` id are stacked together. */
+  stack?: string;
+  /** `secondary` pins the series to the 2nd value axis (dual-axis). */
+  axis?: "primary" | "secondary";
+}
+
+/** Chart-level enumerated options (no strings that become code). */
+export interface ChartOptions {
+  /** Render a legend (needed once there are ≥2 series). */
+  legend?: boolean;
+  /** Cartesian orientation: `vertical` = category on x (default). */
+  orientation?: "horizontal" | "vertical";
+  /** Enable a 2nd value axis for `axis: "secondary"` series. */
+  y_secondary?: boolean;
+  /** Pie/donut hole as a fraction of the outer radius (0 = full pie). */
+  inner_radius?: number;
+}
+
+/** The declarative chart spec carried on a chart block's props. */
+export interface ChartSpec {
+  /** Aggregate VIEW code (also lives on the block binding/entity). */
+  view_code?: string;
+  /** The category (x / pie-angle) column. */
+  category: { column: string };
+  /** ≥1 series; ≥2 = multi-series. */
+  series: ChartSeriesSpec[];
+  options?: ChartOptions;
+  /** Defensive client-side row cap (server `?limit=` is authoritative). */
+  limit?: number;
+  /** Echoes the binding order term (for reference; ordering is server-side). */
+  order_by?: string;
+}
+
+/** A column-aligned series ready for the renderer. */
+export interface SeriesData {
+  name: string;
+  type: ChartSeriesType;
+  data: number[];
+  stack?: string;
+  axis?: "primary" | "secondary";
+}
+
+/** The shape `EChart` / `ResultsChart` render: aligned category + series. */
+export interface ChartData {
+  category: string[];
+  series: SeriesData[];
+}
+
+/**
+ * Project resolved VIEW rows → `{ category, series[] }` per a `ChartSpec`.
+ * Pure: rows are never mutated and never re-sorted (order is the binding's
+ * job). Blank-category rows are dropped (they have no axis tick) — dropping a
+ * row removes that index from EVERY series so the columns stay aligned. A
+ * non-numeric cell coerces to 0 (fail-soft, same as `toRankedItems`).
+ */
+export function toSeriesData(
+  rows: ReadonlyArray<Record<string, unknown>>,
+  spec: ChartSpec,
+): ChartData {
+  const categoryCol = spec.category?.column;
+  const series = Array.isArray(spec.series) ? spec.series : [];
+  if (!categoryCol || series.length === 0) {
+    return { category: [], series: [] };
+  }
+
+  // Drop blank-category rows first so every series stays index-aligned.
+  const kept = rows.filter((row) => {
+    const c = row[categoryCol];
+    return c != null && String(c) !== "";
+  });
+
+  const capped =
+    spec.limit && spec.limit > 0 ? kept.slice(0, Math.floor(spec.limit)) : kept;
+
+  const category = capped.map((row) => String(row[categoryCol]));
+
+  const shaped: SeriesData[] = series.map((s) => ({
+    name: s.name && s.name.trim() ? s.name : s.column,
+    type: s.type,
+    data: capped.map((row) => toNumber(row[s.column])),
+    ...(s.stack ? { stack: s.stack } : {}),
+    ...(s.axis ? { axis: s.axis } : {}),
+  }));
+
+  return { category, series: shaped };
+}

package/components/renderer/chart-option.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Declarative chart → ECharts `option` builder (#176 follow-on) — PURE.
+ *
+ * The single place that turns a column-aligned `{ category, series[] }`
+ * (`ChartData`, produced by `toSeriesData`) into an Apache ECharts `option`.
+ * Extracted out of `EChart.svelte` so it is unit-testable with real inputs
+ * (no mocking ECharts): feed it a `ChartData` + theme tokens and assert on the
+ * produced option's structure.
+ *
+ * Theming is token-driven (the caller reads the live `--color-*` tokens off the
+ * chart container and passes them in) — there is NO hardcoded colour list; the
+ * per-series / per-slice palette is an ALPHA RAMP off the single `--color-accent`
+ * so any number of series stays on-theme through dark / high-contrast schemes.
+ *
+ * The option CONTAINS DS-supplied formatter functions (locale number formatting,
+ * tooltip composition). That is deliberate and does NOT violate the JSON-only
+ * constraint — the constraint forbids OPERATOR-authored functions in the spec;
+ * the behaviours here are the DS's own, chosen from the curated surface. The
+ * returned object is handed straight to `chart.setOption` in-process; it is not
+ * serialised.
+ */
+import type { ChartData } from "./aggregate";
+/** Live semantic tokens read off the chart container. */
+export interface ChartTokens {
+    accent: string;
+    textPrimary: string;
+    textSecondary: string;
+    border: string;
+}
+export interface BuildChartOptionOpts {
+    tokens: ChartTokens;
+    /** BCP-47 locale for number formatting. */
+    locale?: string;
+    /** Render a legend (auto-on is the caller's decision). */
+    legend?: boolean;
+    /** Cartesian orientation; `vertical` (category on x) is the default. */
+    orientation?: "horizontal" | "vertical";
+    /** Enable a 2nd value axis for `axis: "secondary"` series. */
+    ySecondary?: boolean;
+    /** Pie/donut hole as a fraction of the outer radius (0 = full pie). */
+    innerRadius?: number;
+}
+/**
+ * Per-series / per-slice colour: an alpha ramp off the accent so N series stay
+ * distinguishable AND on-theme without a hardcoded palette. `color-mix` keeps
+ * it in the live colour space, so it re-themes with the tokens.
+ */
+export declare function seriesColor(accent: string, i: number): string;
+/**
+ * Build the ECharts `option` for a declarative chart. Pie (single-measure) and
+ * cartesian (bar/line/area/scatter, optionally stacked / dual-axis) are the two
+ * shapes; the first series' `type` selects pie vs cartesian.
+ */
+export declare function buildChartOption(data: ChartData, opts: BuildChartOptionOpts): Record<string, unknown>;