@aiaiai-pt/design-system 0.35.0 → 0.37.0

package/components/EChart.svelte

@@ -54,6 +54,11 @@
     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} */
@@ -90,9 +95,73 @@
     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.
+    // 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 {
@@ -150,6 +219,8 @@
 
         core.use([
           charts.BarChart,
+          charts.LineChart,
+          charts.PieChart,
           components.GridComponent,
           components.TooltipComponent,
           renderers.CanvasRenderer,
@@ -187,7 +258,10 @@
     // touch reactive deps so the effect re-runs when they change
     void items;
     void locale;
-    if (_chart) _chart.setOption(buildOption());
+    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.
+    if (_chart) _chart.setOption(buildOption(), true);
   });
 </script>
 

package/components/renderer/DonutChartWidget.svelte

@@ -0,0 +1,11 @@
+<script lang="ts">
+  import EChartWidget from "./EChartWidget.svelte";
+  import type { WidgetProps } from "./types";
+
+  // `donut-chart` registry key (#176 Tier 1). Thin wrapper binding the ECharts
+  // `kind` to a ring pie — the registry maps this key here. Same aggregate data
+  // path + a11y data table as the bar/line.
+  let p: WidgetProps = $props();
+</script>
+
+<EChartWidget {...p} kind="donut" />

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

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

package/components/renderer/EChartWidget.svelte

@@ -11,7 +11,12 @@
   // 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();
+  // `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.
+  let { data, props, ownsH1, locale, kind = "bar" }: WidgetProps & {
+    kind?: "bar" | "line" | "donut";
+  } = $props();
 
   const rows = $derived(
     data && typeof data === "object" && Array.isArray((data as { items?: unknown }).items)
@@ -63,6 +68,7 @@
       {caption}
       {labelHeader}
       {valueHeader}
+      {kind}
       locale={locale ?? "en"}
     />
   </section>

package/components/renderer/LineChartWidget.svelte

@@ -0,0 +1,12 @@
+<script lang="ts">
+  import EChartWidget from "./EChartWidget.svelte";
+  import type { WidgetProps } from "./types";
+
+  // `line-chart` registry key (#176 Tier 1). Thin wrapper that binds the ECharts
+  // `kind` the dispatcher can't pass — the registry maps this key to this
+  // component, which renders the shared EChart widget as a line. Same aggregate
+  // data path + a11y data table as the bar.
+  let p: WidgetProps = $props();
+</script>
+
+<EChartWidget {...p} kind="line" />

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

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

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,7 +22,9 @@ import {
 } from "./dispatch";
 import type { Block, OntologySchema, WidgetKind, WidgetProps } from "./types";
 
+import DonutChartWidget from "./DonutChartWidget.svelte";
 import EChartWidget from "./EChartWidget.svelte";
+import LineChartWidget from "./LineChartWidget.svelte";
 import ResultsChartWidget from "./ResultsChartWidget.svelte";
 import StatGridWidget from "./StatGridWidget.svelte";
 
@@ -69,6 +71,11 @@ const _entries: RegistryEntry<WidgetComponent>[] = [
   byKind("stat-grid", "kpi", StatGridWidget),
   byTypeOnKind("results-chart", "aggregate", ResultsChartWidget),
   byTypeOnKind("chart", "aggregate", EChartWidget),
+  // #176 Tier 1 — chart KINDS as registry entries, so the authoring `type`
+  // picker is a real chart picker. All three ECharts kinds share the same
+  // aggregate data path + a11y data table; only the rendered geometry differs.
+  byTypeOnKind("line-chart", "aggregate", LineChartWidget),
+  byTypeOnKind("donut-chart", "aggregate", DonutChartWidget),
 ];
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiaiai-pt/design-system",
-  "version": "0.35.0",
+  "version": "0.37.0",
   "description": "Design system tokens and Svelte components for aiaiai products",
   "license": "MIT",
   "type": "module",