feat(ui): add period-over-period comparison and chart series styling

Author: os-zhuang

.changeset/spec-dashboard-compare-to.md

@@ -0,0 +1,12 @@
+---
+"@objectstack/spec": minor
+---
+
+Add `compareTo` field to `DashboardWidgetSchema` and `variant` / `dashArray` /
+`opacity` to `ChartSeriesSchema` so renderers can express period-over-period
+overlays on metric / gauge / chart widgets.
+
+`compareTo` accepts `'previousPeriod'`, `'previousYear'`, or
+`{ offset: '7d' | '4w' | '1M' | '1y' }`. The renderer issues a second query
+against the shifted filter and either (a) derives a trend delta for KPI
+widgets or (b) overlays a muted comparison series on cartesian charts.

examples/app-crm/src/dashboards/pipeline.dashboard.ts

@@ -2,12 +2,31 @@
 
 import type { Dashboard } from '@objectstack/spec/ui';
 
+/**
+ * Pipeline Dashboard — aggregate view of the sales pipeline.
+ *
+ * Demonstrates period-over-period comparison via `compareTo`:
+ *
+ * - **Won This Quarter** — metric with `compareTo: 'previousPeriod'`. The
+ *   filter uses `{current_quarter_start}` / `{current_quarter_end}`, so
+ *   the renderer issues a parallel aggregate for Q-1 and shows a delta
+ *   labelled "vs last quarter".
+ * - **Avg Deal Size YoY** — metric with `compareTo: 'previousYear'` to
+ *   compare against the same window one year prior.
+ * - **Pipeline Trend (90d)** — line chart with a sliding
+ *   `compareTo: { offset: '90d' }` overlay, rendered as a dashed muted
+ *   series on top of the current 90-day trend.
+ * - **Opportunities by Stage** / **Pipeline by Industry** — bar / pie
+ *   examples without `compareTo` (pie / donut / funnel ignore overlays
+ *   even if set).
+ */
 export const PipelineDashboard: Dashboard = {
   name: 'pipeline_dashboard',
   label: 'Pipeline Dashboard',
-  description: 'Aggregate view of the sales pipeline.',
+  description: 'Aggregate view of the sales pipeline with period-over-period comparisons.',
   columns: 12,
   widgets: [
+    // --- Row 1: KPI tiles -------------------------------------------------
     {
       id: 'total_pipeline',
       type: 'metric',
@@ -17,8 +36,63 @@ export const PipelineDashboard: Dashboard = {
       aggregate: 'sum',
       valueField: 'amount',
       filter: { stage: { $nin: ['closed_won', 'closed_lost'] } },
+      options: { format: 'currency', currency: 'USD' },
       layout: { x: 0, y: 0, w: 4, h: 2 },
     },
+    {
+      id: 'won_this_quarter',
+      type: 'metric',
+      title: 'Won This Quarter',
+      description: 'Revenue closed-won in the current quarter, compared to the previous quarter.',
+      object: 'crm_opportunity',
+      aggregate: 'sum',
+      valueField: 'amount',
+      filter: {
+        stage: 'closed_won',
+        close_date: {
+          $gte: '{current_quarter_start}',
+          $lte: '{current_quarter_end}',
+        },
+      },
+      compareTo: 'previousPeriod',
+      options: { format: 'currency', currency: 'USD' },
+      layout: { x: 4, y: 0, w: 4, h: 2 },
+    },
+    {
+      id: 'avg_deal_size_yoy',
+      type: 'metric',
+      title: 'Avg Deal Size (YoY)',
+      description: 'Average won-deal value this year vs the same window last year.',
+      object: 'crm_opportunity',
+      aggregate: 'avg',
+      valueField: 'amount',
+      filter: {
+        stage: 'closed_won',
+        close_date: {
+          $gte: '{current_year_start}',
+          $lte: '{current_year_end}',
+        },
+      },
+      compareTo: 'previousYear',
+      options: { format: 'currency', currency: 'USD' },
+      layout: { x: 8, y: 0, w: 4, h: 2 },
+    },
+
+    // --- Row 2: Trend + breakdown ----------------------------------------
+    {
+      id: 'pipeline_trend_90d',
+      type: 'line',
+      title: 'Pipeline Trend (90d)',
+      description: 'Daily count of opportunities created in the last 90 days, with a sliding overlay of the prior 90-day window.',
+      object: 'crm_opportunity',
+      aggregate: 'count',
+      categoryField: 'close_date',
+      filter: {
+        close_date: { $gte: '{90_days_ago}', $lte: '{today}' },
+      },
+      compareTo: { offset: '90d' },
+      layout: { x: 0, y: 2, w: 8, h: 4 },
+    },
     {
       id: 'opportunities_by_stage',
       type: 'bar',
@@ -27,7 +101,22 @@ export const PipelineDashboard: Dashboard = {
       object: 'crm_opportunity',
       aggregate: 'count',
       categoryField: 'stage',
-      layout: { x: 4, y: 0, w: 8, h: 4 },
+      layout: { x: 8, y: 2, w: 4, h: 4 },
+    },
+
+    // --- Row 3: Mix breakdown (pie ignores compareTo, even if set) -------
+    {
+      id: 'pipeline_by_industry',
+      type: 'pie',
+      title: 'Open Pipeline by Stage ($)',
+      description: 'Open-pipeline revenue split by pipeline stage. Pie/donut/funnel ignore `compareTo`.',
+      object: 'crm_opportunity',
+      aggregate: 'sum',
+      valueField: 'amount',
+      categoryField: 'stage',
+      filter: { stage: { $nin: ['closed_won', 'closed_lost'] } },
+      layout: { x: 0, y: 6, w: 6, h: 4 },
     },
   ],
 };
+

examples/app-crm/src/data/index.ts

@@ -30,9 +30,27 @@ const opportunities = defineDataset(Opportunity, {
   mode: 'upsert',
   externalId: 'name',
   records: [
+    // --- Open pipeline (no close yet) -----------------------------------
     { name: 'Acme — Q3 Platform Renewal', account: { externalId: 'Acme Corp' },  stage: 'proposal',       amount: 120_000, probability: 70, close_date: cel`daysFromNow(30)` },
     { name: 'Globex — New CRM Rollout',   account: { externalId: 'Globex Ltd' }, stage: 'qualification',  amount: 450_000, probability: 40, close_date: cel`daysFromNow(60)` },
-    { name: 'Initech — Pilot',            account: { externalId: 'Initech' },    stage: 'closed_won',     amount:  35_000, probability: 100, close_date: cel`daysAgo(7)` },
+    { name: 'Initech — Expansion',        account: { externalId: 'Initech' },    stage: 'prospecting',    amount:  80_000, probability: 20, close_date: cel`daysFromNow(45)` },
+    { name: 'Acme — Add-on Module',       account: { externalId: 'Acme Corp' },  stage: 'qualification',  amount:  60_000, probability: 35, close_date: cel`daysFromNow(20)` },
+
+    // --- Recently closed-won (current quarter — drives "Won This Quarter") -
+    { name: 'Initech — Pilot',                  account: { externalId: 'Initech' },    stage: 'closed_won', amount:  35_000, probability: 100, close_date: cel`daysAgo(7)` },
+    { name: 'Acme — Support Tier Upgrade',      account: { externalId: 'Acme Corp' },  stage: 'closed_won', amount:  90_000, probability: 100, close_date: cel`daysAgo(14)` },
+    { name: 'Globex — Analytics Pack',          account: { externalId: 'Globex Ltd' }, stage: 'closed_won', amount: 110_000, probability: 100, close_date: cel`daysAgo(21)` },
+
+    // --- Previous-quarter wins (drives the "vs last quarter" comparison) ---
+    { name: 'Initech — POC',                    account: { externalId: 'Initech' },    stage: 'closed_won', amount:  25_000, probability: 100, close_date: cel`daysAgo(95)` },
+    { name: 'Globex — Initial Seats',           account: { externalId: 'Globex Ltd' }, stage: 'closed_won', amount: 145_000, probability: 100, close_date: cel`daysAgo(110)` },
+
+    // --- Prior-year wins in the same window (drives "YoY" comparison) ------
+    { name: 'Acme — Year-Ago Renewal',          account: { externalId: 'Acme Corp' },  stage: 'closed_won', amount:  75_000, probability: 100, close_date: cel`daysAgo(380)` },
+    { name: 'Globex — Year-Ago Implementation', account: { externalId: 'Globex Ltd' }, stage: 'closed_won', amount: 210_000, probability: 100, close_date: cel`daysAgo(400)` },
+
+    // --- Closed lost (kept out of pipeline sum) ----------------------------
+    { name: 'Initech — Cancelled Eval',         account: { externalId: 'Initech' },    stage: 'closed_lost', amount: 15_000, probability: 0, close_date: cel`daysAgo(30)` },
   ],
 });
 

examples/app-crm/test/smoke.test.ts

@@ -2,6 +2,7 @@
 
 import { describe, it, expect } from 'vitest';
 import stack from '../objectstack.config.js';
+import { PipelineDashboard } from '../src/dashboards/pipeline.dashboard.js';
 
 describe('app-crm minimal metadata bundle', () => {
   it('exposes the expected manifest', () => {
@@ -27,3 +28,79 @@ describe('app-crm minimal metadata bundle', () => {
     expect((stack.data ?? []).length).toBeGreaterThanOrEqual(3);
   });
 });
+
+describe('Pipeline dashboard', () => {
+  const byId = new Map(PipelineDashboard.widgets.map((w: any) => [w.id, w]));
+
+  it('lays out all 6 widgets', () => {
+    expect(PipelineDashboard.widgets).toHaveLength(6);
+    expect([...byId.keys()].sort()).toEqual(
+      [
+        'avg_deal_size_yoy',
+        'opportunities_by_stage',
+        'pipeline_by_industry',
+        'pipeline_trend_90d',
+        'total_pipeline',
+        'won_this_quarter',
+      ],
+    );
+  });
+
+  it('uses `compareTo: previousPeriod` for the current-quarter KPI', () => {
+    const w: any = byId.get('won_this_quarter');
+    expect(w.compareTo).toBe('previousPeriod');
+    expect(w.filter.close_date.$gte).toBe('{current_quarter_start}');
+    expect(w.filter.close_date.$lte).toBe('{current_quarter_end}');
+  });
+
+  it('uses `compareTo: previousYear` for the YoY KPI', () => {
+    const w: any = byId.get('avg_deal_size_yoy');
+    expect(w.compareTo).toBe('previousYear');
+    expect(w.filter.close_date.$gte).toBe('{current_year_start}');
+    expect(w.filter.close_date.$lte).toBe('{current_year_end}');
+  });
+
+  it('uses a sliding `{ offset }` compareTo on the trend chart', () => {
+    const w: any = byId.get('pipeline_trend_90d');
+    expect(w.compareTo).toEqual({ offset: '90d' });
+    expect(w.type).toBe('line');
+  });
+
+  it('omits compareTo on widgets that do not need it (pie, plain bar, total)', () => {
+    expect((byId.get('total_pipeline') as any).compareTo).toBeUndefined();
+    expect((byId.get('opportunities_by_stage') as any).compareTo).toBeUndefined();
+    expect((byId.get('pipeline_by_industry') as any).compareTo).toBeUndefined();
+  });
+
+  it('widgets bind to the opportunity object', () => {
+    for (const w of PipelineDashboard.widgets) {
+      expect((w as any).object).toBe('crm_opportunity');
+    }
+  });
+
+  it('layout positions do not overlap and fit within 12 columns', () => {
+    const cells: Record<string, string> = {};
+    for (const w of PipelineDashboard.widgets as any[]) {
+      const { x, y, w: ww, h } = w.layout;
+      expect(x + ww).toBeLessThanOrEqual(12);
+      for (let i = x; i < x + ww; i++) {
+        for (let j = y; j < y + h; j++) {
+          const key = `${i},${j}`;
+          if (cells[key]) {
+            throw new Error(`Widget ${w.id} overlaps ${cells[key]} at ${key}`);
+          }
+          cells[key] = w.id;
+        }
+      }
+    }
+  });
+});
+
+describe('Pipeline dashboard schema validation', () => {
+  it('passes the DashboardSchema zod parser end-to-end', async () => {
+    const { DashboardSchema } = await import('@objectstack/spec/ui');
+    const parsed = DashboardSchema.parse(PipelineDashboard);
+    expect(parsed.name).toBe('pipeline_dashboard');
+    expect(parsed.widgets).toHaveLength(6);
+  });
+});