@object-ui/core 6.0.4 → 6.1.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @object-ui/core
 
+## 6.1.0
+
+### Minor Changes
+
+- 991b62d: Add `compareTo` field to dashboard widgets for period-over-period
+  comparison. Supports `'previousPeriod'`, `'previousYear'`, and
+  `{ offset: '7d' | '4w' | '1M' | '1y' }`.
+  - **Metric / gauge widgets** now compute a delta percentage when `compareTo`
+    is set and surface it as a derived `trend` (auto-labelled via
+    `dashboard.trend.vsLast*` i18n keys sniffed from the filter macros).
+  - **Chart widgets** (line / area / bar / horizontal-bar / scatter / combo)
+    overlay a muted comparison-period series (dashed line, lower fill opacity).
+    Pie / donut / funnel ignore `compareTo`.
+  - New core utilities: `shiftFilterByCompareTo`, `compareToTrendLabelKey`,
+    `computeMetricDelta`, and `CompareToConfig` type.
+  - `ChartSeries` now accepts `variant: 'comparison'`, `dashArray`, and
+    `opacity` overrides for visual treatment.
+
+  See `packages/plugin-dashboard/SKILL.md` for usage examples.
+
+### Patch Changes
+
+- Updated dependencies [991b62d]
+  - @object-ui/types@6.1.0
+
 ## 6.0.4
 
 ### Patch Changes

package/dist/index.d.ts

@@ -37,3 +37,4 @@ export * from './protocols/index.js';
 export { composeStacks } from '@objectstack/spec';
 export * from './utils/drill-down.js';
 export * from './utils/date-macros.js';
+export * from './utils/compare-to.js';

package/dist/index.js

@@ -36,3 +36,4 @@ export * from './protocols/index.js';
 export { composeStacks } from '@objectstack/spec';
 export * from './utils/drill-down.js';
 export * from './utils/date-macros.js';
+export * from './utils/compare-to.js';

package/dist/utils/compare-to.d.ts

@@ -0,0 +1,36 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Period-over-period comparison config for dashboard widgets.
+ *
+ * - `'previousPeriod'` — substitute `current_*` / `today` date macro tokens
+ *   with their `last_*` / `yesterday` counterparts (e.g. `current_quarter_start`
+ *   → `last_quarter_start`). Best when the filter uses date macros.
+ * - `'previousYear'` — re-resolve date macros against a `now` shifted back
+ *   one calendar year (same week / month / quarter, one year earlier).
+ * - `{ offset: '7d' | '4w' | '1M' | '1y' }` — re-resolve macros against a
+ *   `now` shifted by the given duration. Units: `d` (day), `w` (week),
+ *   `M` (month), `y` (year).
+ */
+export type CompareToConfig = 'previousPeriod' | 'previousYear' | {
+    offset: string;
+};
+/**
+ * Resolve a filter for a period-over-period comparison query.
+ *
+ * - `previousYear` — re-resolve date macros against a `now` shifted back by one year.
+ * - `{ offset }` — re-resolve date macros against a `now` shifted by the given duration.
+ * - `previousPeriod` — substitute `current_*` / `today` tokens with `last_*` / `yesterday`
+ *   before resolving.
+ */
+export declare function shiftFilterByCompareTo<T = any>(filter: T, compareTo: CompareToConfig, now?: Date): T;
+/**
+ * Derive a translation key suffix (under `dashboard.trend.*`) describing the
+ * comparison window. Used by metric widgets to label the trend delta.
+ */
+export declare function compareToTrendLabelKey(compareTo: CompareToConfig, filter?: unknown): string;

package/dist/utils/compare-to.js

@@ -0,0 +1,112 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { resolveDateMacros } from './date-macros.js';
+const CURRENT_TO_LAST_TOKENS = {
+    current_week_start: 'last_week_start',
+    current_week_end: 'last_week_end',
+    current_month_start: 'last_month_start',
+    current_month_end: 'last_month_end',
+    current_quarter_start: 'last_quarter_start',
+    current_quarter_end: 'last_quarter_end',
+    current_year_start: 'last_year_start',
+    current_year_end: 'last_year_end',
+    week_start: 'last_week_start',
+    week_end: 'last_week_end',
+    month_start: 'last_month_start',
+    month_end: 'last_month_end',
+    quarter_start: 'last_quarter_start',
+    quarter_end: 'last_quarter_end',
+    year_start: 'last_year_start',
+    year_end: 'last_year_end',
+    today: 'yesterday',
+};
+function substituteTokens(value, map) {
+    if (value == null)
+        return value;
+    if (typeof value === 'string') {
+        return value.replace(/\$?\{([a-zA-Z0-9_]+)\}/g, (m, tok) => {
+            const target = map[tok];
+            return target ? `{${target}}` : m;
+        });
+    }
+    if (Array.isArray(value))
+        return value.map((v) => substituteTokens(v, map));
+    if (typeof value === 'object') {
+        const out = {};
+        for (const k of Object.keys(value))
+            out[k] = substituteTokens(value[k], map);
+        return out;
+    }
+    return value;
+}
+function shiftNow(now, offset) {
+    const m = offset.match(/^(\d+)([dwMy])$/);
+    if (!m)
+        return null;
+    const n = parseInt(m[1], 10);
+    const unit = m[2];
+    const x = new Date(now);
+    if (unit === 'd')
+        x.setDate(x.getDate() - n);
+    else if (unit === 'w')
+        x.setDate(x.getDate() - n * 7);
+    else if (unit === 'M')
+        x.setMonth(x.getMonth() - n);
+    else if (unit === 'y')
+        x.setFullYear(x.getFullYear() - n);
+    else
+        return null;
+    return x;
+}
+/**
+ * Resolve a filter for a period-over-period comparison query.
+ *
+ * - `previousYear` — re-resolve date macros against a `now` shifted back by one year.
+ * - `{ offset }` — re-resolve date macros against a `now` shifted by the given duration.
+ * - `previousPeriod` — substitute `current_*` / `today` tokens with `last_*` / `yesterday`
+ *   before resolving.
+ */
+export function shiftFilterByCompareTo(filter, compareTo, now = new Date()) {
+    if (compareTo === 'previousYear') {
+        const shifted = new Date(now.getFullYear() - 1, now.getMonth(), now.getDate(), now.getHours(), now.getMinutes(), now.getSeconds());
+        return resolveDateMacros(filter, shifted);
+    }
+    if (typeof compareTo === 'object' && compareTo && 'offset' in compareTo) {
+        const shifted = shiftNow(now, compareTo.offset);
+        if (!shifted)
+            return resolveDateMacros(filter, now);
+        return resolveDateMacros(filter, shifted);
+    }
+    // previousPeriod
+    const substituted = substituteTokens(filter, CURRENT_TO_LAST_TOKENS);
+    return resolveDateMacros(substituted, now);
+}
+/**
+ * Derive a translation key suffix (under `dashboard.trend.*`) describing the
+ * comparison window. Used by metric widgets to label the trend delta.
+ */
+export function compareToTrendLabelKey(compareTo, filter) {
+    if (compareTo === 'previousYear')
+        return 'vsLastYear';
+    if (typeof compareTo === 'object' && compareTo && 'offset' in compareTo) {
+        return 'vsPreviousPeriod';
+    }
+    // previousPeriod — sniff the dominant token in the filter
+    const json = filter ? JSON.stringify(filter) : '';
+    if (/current_year_|year_start|year_end/.test(json))
+        return 'vsLastYear';
+    if (/current_quarter_|quarter_start|quarter_end/.test(json))
+        return 'vsLastQuarter';
+    if (/current_month_|month_start|month_end/.test(json))
+        return 'vsLastMonth';
+    if (/current_week_|week_start|week_end/.test(json))
+        return 'vsLastWeek';
+    if (/\btoday\b/.test(json))
+        return 'vsYesterday';
+    return 'vsPreviousPeriod';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/core",
-  "version": "6.0.4",
+  "version": "6.1.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -28,11 +28,11 @@
     "@objectstack/spec": "^5.2.0",
     "lodash": "^4.18.1",
     "zod": "^4.4.3",
-    "@object-ui/types": "6.0.4"
+    "@object-ui/types": "6.1.0"
   },
   "devDependencies": {
     "typescript": "^6.0.3",
-    "vitest": "^4.1.6"
+    "vitest": "^4.1.7"
   },
   "keywords": [
     "objectui",