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

Author: os-zhuang

packages/spec/src/ui/chart.zod.ts

@@ -124,6 +124,24 @@ export const ChartSeriesSchema = lazySchema(() => z.object({
 
   /** Axis binding */
   yAxis: z.enum(['left', 'right']).default('left').describe('Bind to specific Y-Axis'),
+
+  /**
+   * Series role.
+   *
+   * - `'primary'` (default) — normal styling using the chart palette.
+   * - `'comparison'` — secondary period-over-period overlay; renderers
+   *   render it muted (lower opacity, dashed stroke for line/area,
+   *   lighter fill for bars) so it visually backgrounds against the
+   *   primary series. Pair with `DashboardWidget.compareTo` on data-
+   *   bound charts; for hand-authored series, set it directly.
+   */
+  variant: z.enum(['primary', 'comparison']).default('primary').optional().describe('Series visual role'),
+
+  /** Override stroke dash pattern (e.g. "4 4" for dashed lines). */
+  dashArray: z.string().optional().describe('SVG stroke-dasharray override'),
+
+  /** Override series opacity (0–1). */
+  opacity: z.number().min(0).max(1).optional().describe('Series opacity override'),
 }));
 
 /**

packages/spec/src/ui/dashboard.zod.ts

@@ -142,7 +142,32 @@ export const DashboardWidgetSchema = lazySchema(() => z.object({
 
   /** Data Filter (MongoDB-style FilterCondition) */
   filter: FilterConditionSchema.optional().describe('Data filter criteria'),
-  
+
+  /**
+   * Period-over-period comparison primitive.
+   *
+   * When set, the renderer runs a second query against a shifted time
+   * window and surfaces the delta (metric widgets show a secondary
+   * value + arrow; chart widgets render a muted/dashed overlay series).
+   *
+   * - `'previousPeriod'` — auto-detect the comparison window from the
+   *   widget's `filter` date macros (e.g. `{current_month_start}` →
+   *   `{last_month_start}`). Falls back to no comparison when the
+   *   filter contains no resolvable date range.
+   * - `'previousYear'` — shift the resolved filter window back by one
+   *   calendar year.
+   * - `{ offset: '7d' | '1M' | '1y' }` — shift by an explicit
+   *   ISO-8601-like duration. Units: `d` (days), `w` (weeks),
+   *   `M` (months), `y` (years).
+   */
+  compareTo: z.union([
+    z.literal('previousPeriod'),
+    z.literal('previousYear'),
+    z.object({
+      offset: z.string().regex(/^\d+[dwMy]$/, 'Offset must match <N>(d|w|M|y), e.g. "7d", "1M", "1y"'),
+    }),
+  ]).optional().describe('Period-over-period comparison window'),
+
   /** Category Field (X-Axis / Group By) */
   categoryField: z.string().optional().describe('Field for grouping (X-Axis)'),
 

skills/objectstack-ui/SKILL.md

@@ -450,12 +450,25 @@ export const SalesDashboard: Dashboard = {
       filter: { stage: { $nin: ['closed_won', 'closed_lost'] } },
       valueField: 'amount', aggregate: 'sum',
       layout: { x: 0, y: 0, w: 3, h: 2 },
-      options: {
-        icon: 'DollarSign', format: '0,0',
-        trend: { value: 8.4, direction: 'up', label: 'vs last quarter' },
-      },
+      options: { icon: 'DollarSign', format: '0,0' },
+      // Period-over-period: renderer fetches the prior quarter and
+      // surfaces a secondary value + delta arrow automatically.
+      compareTo: 'previousPeriod',
       actionType: 'url', actionUrl: '/objects/opportunity?filter=open',
     },
+
+    // Chart widget with comparison overlay (M2). The renderer issues a
+    // second query with the time window shifted by `compareTo` and
+    // overlays it as a muted/dashed series.
+    {
+      id: 'revenue_vs_last_year', type: 'line',
+      title: 'Revenue — This Year vs Last',
+      object: 'order',
+      filter: { closed_at: { $gte: '{current_year_start}', $lte: '{current_year_end}' } },
+      categoryField: 'closed_at', valueField: 'total', aggregate: 'sum',
+      compareTo: 'previousYear',
+      layout: { x: 3, y: 0, w: 9, h: 4 },
+    },
   ],
 };
 ```
@@ -465,6 +478,29 @@ export const SalesDashboard: Dashboard = {
 > The full list of supported date placeholders is documented in
 > [Date Macros](#date-macros--filter-placeholders) below.
 
+### Period-over-period — `compareTo`
+
+Set `compareTo` on any data-bound widget to add a second query against a
+shifted time window. The renderer derives the comparison automatically;
+no second `filter` is required.
+
+| Value | Behaviour |
+|:--|:--|
+| `'previousPeriod'` | Inspect the widget `filter` for date-macro tokens (`{current_month_start}`, `{last_7_days}`, …) and shift the window back by one period of the same kind. |
+| `'previousYear'`   | Shift the resolved filter window back by one calendar year. |
+| `{ offset: '7d' }` | Shift by an explicit duration. Units: `d` (days), `w` (weeks), `M` (months), `y` (years). |
+
+* **Metric widgets** — the prior-period value renders as a small caption
+  beneath the headline number, alongside a green/red delta arrow.
+  Authors should *not* hand-author `options.trend` when `compareTo` is
+  set; the renderer wins and overwrites it.
+* **Chart widgets** — the comparison series is appended after the
+  primary series with `variant: 'comparison'` and styled as a muted /
+  dashed overlay. Single-series charts (bar / line / area) get an
+  automatic second series; multi-series pivots are not yet supported.
+* **Requirements** — `compareTo` is a no-op when the filter contains no
+  resolvable date macros and no global `dateRange` is configured.
+
 ---
 
 ## Date Macros — Filter Placeholders