@aiaiai-pt/design-system 0.36.0 → 0.38.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/grid.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Grid layout helpers (#176 Tier 1 / ADR 0003).
+ *
+ * A page is still a flat `Block[]`; a block may carry an optional `layout`
+ * placing it on a 12-column grid. These pure helpers turn that descriptor field
+ * into CSS, shared by BOTH host apps (admin dashboard + portal page) so the
+ * arrangement is identical and DRY. Presentation-only: no editing concern lives
+ * here — the editor merely writes the same `layout` coords the renderer reads.
+ *
+ * Back-compatible: a block without `layout` falls back to source order, and a
+ * page with NO laid-out blocks renders as the shipped stacked list.
+ */
+import type { Block, BlockLayout } from "./types";
+export declare const GRID_COLUMNS = 12;
+/** Clamp a layout to valid 12-col track bounds (defensive against operator /
+ *  drag input). `w` is 1..12; `x` keeps the span on-track; `y`/`h` are >=0/>=1. */
+export declare function normalizeLayout(layout: BlockLayout): BlockLayout;
+/**
+ * CSS `grid-column` / `grid-row` placement for a block's layout, or `null` when
+ * the block has none (the caller renders it in source order). Grid lines are
+ * 1-based, so a 0-based `x`/`y` maps to line `x+1`/`y+1`.
+ */
+export declare function gridStyleFor(block: Pick<Block, "layout">): string | null;
+/** True when ANY block carries a `layout` — the page should render as a grid
+ *  (12-col track) rather than the stacked list. */
+export declare function hasGridLayout(blocks: ReadonlyArray<Pick<Block, "layout">>): boolean;

package/components/renderer/grid.ts

@@ -0,0 +1,57 @@
+/**
+ * Grid layout helpers (#176 Tier 1 / ADR 0003).
+ *
+ * A page is still a flat `Block[]`; a block may carry an optional `layout`
+ * placing it on a 12-column grid. These pure helpers turn that descriptor field
+ * into CSS, shared by BOTH host apps (admin dashboard + portal page) so the
+ * arrangement is identical and DRY. Presentation-only: no editing concern lives
+ * here — the editor merely writes the same `layout` coords the renderer reads.
+ *
+ * Back-compatible: a block without `layout` falls back to source order, and a
+ * page with NO laid-out blocks renders as the shipped stacked list.
+ */
+import type { Block, BlockLayout } from "./types";
+
+export const GRID_COLUMNS = 12;
+
+/** Clamp a layout to valid 12-col track bounds (defensive against operator /
+ *  drag input). `w` is 1..12; `x` keeps the span on-track; `y`/`h` are >=0/>=1. */
+export function normalizeLayout(layout: BlockLayout): BlockLayout {
+  const w = clampInt(layout.w, 1, GRID_COLUMNS, 1);
+  const x = clampInt(layout.x, 0, GRID_COLUMNS - w, 0);
+  const h = clampInt(layout.h, 1, Number.MAX_SAFE_INTEGER, 1);
+  const y = clampInt(layout.y, 0, Number.MAX_SAFE_INTEGER, 0);
+  return { x, y, w, h };
+}
+
+/**
+ * CSS `grid-column` / `grid-row` placement for a block's layout, or `null` when
+ * the block has none (the caller renders it in source order). Grid lines are
+ * 1-based, so a 0-based `x`/`y` maps to line `x+1`/`y+1`.
+ */
+export function gridStyleFor(block: Pick<Block, "layout">): string | null {
+  if (!block.layout) return null;
+  const { x, y, w, h } = normalizeLayout(block.layout);
+  return `grid-column:${x + 1} / span ${w};grid-row:${y + 1} / span ${h};`;
+}
+
+/** True when ANY block carries a `layout` — the page should render as a grid
+ *  (12-col track) rather than the stacked list. */
+export function hasGridLayout(
+  blocks: ReadonlyArray<Pick<Block, "layout">>,
+): boolean {
+  return blocks.some((b) => b.layout != null);
+}
+
+function clampInt(
+  value: unknown,
+  min: number,
+  max: number,
+  fallback: number,
+): number {
+  const n =
+    typeof value === "number" && Number.isFinite(value)
+      ? Math.round(value)
+      : fallback;
+  return Math.max(min, Math.min(max, n));
+}

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/components/renderer/types.ts

@@ -183,6 +183,34 @@ export interface Block {
    * (set on the default block), not tenant content.
    */
   bleed?: boolean;
+  /**
+   * #176 Tier 1 (ADR 0003) — 2D grid placement on a 12-column track. A block
+   * WITH `layout` is positioned by the renderer's grid (col `x`, span `w`; row
+   * `y`, span `h`); a block WITHOUT it falls back to source order (the shipped
+   * ordered-list behaviour — fully back-compatible). This is a DESCRIPTOR field
+   * consumed by BOTH render (places the block) and authoring (drag/resize writes
+   * the coords); the DS never learns it is being edited. `x`/`y` are 0-based;
+   * `w`/`h` are 1-based spans (w clamped to 1..12).
+   */
+  layout?: BlockLayout;
+  /**
+   * #176 Tier 1 — child blocks for a future grid-IN-grid container. Reserved
+   * (single-level page grids use `layout` on flat blocks); nesting is deferred
+   * until a concrete need (ADR 0003 build-order note).
+   */
+  children?: Block[];
+}
+
+/** 12-column grid placement (#176 Tier 1). All fields in grid track units. */
+export interface BlockLayout {
+  /** 0-based start column (0..11). */
+  x: number;
+  /** 0-based start row. */
+  y: number;
+  /** Column span (1..12). */
+  w: number;
+  /** Row span (>=1). */
+  h: number;
 }
 
 export interface PageDescriptor {

package/package.json

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