@object-ui/core 4.0.7 → 4.0.8

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @object-ui/core
 
+## 4.0.8
+
+### Patch Changes
+
+- @object-ui/types@4.0.8
+
 ## 4.0.7
 
 ### Patch Changes

package/dist/index.d.ts

@@ -35,3 +35,5 @@ export * from './protocols/index.js';
  * in the next major version of `@object-ui/core`.
  */
 export { composeStacks } from '@objectstack/spec';
+export * from './utils/drill-down.js';
+export * from './utils/date-macros.js';

package/dist/index.js

@@ -34,3 +34,5 @@ export * from './protocols/index.js';
  * in the next major version of `@object-ui/core`.
  */
 export { composeStacks } from '@objectstack/spec';
+export * from './utils/drill-down.js';
+export * from './utils/date-macros.js';

package/dist/utils/date-macros.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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.
+ */
+/**
+ * Resolve well-known relative-date placeholders inside a filter object so
+ * both server-side aggregation and client-side `find()` calls see a real
+ * ISO date string instead of a literal `{current_quarter_start}`.
+ *
+ * Supported tokens (case-sensitive, both `{token}` and `${token}` forms):
+ *   - today                      → start of today          (YYYY-MM-DD)
+ *   - now                        → current timestamp       (full ISO)
+ *   - current_week_start         → Monday 00:00 of this week
+ *   - current_month_start        → 1st 00:00 of this month
+ *   - current_quarter_start      → 1st 00:00 of this quarter
+ *   - current_year_start         → Jan 1 00:00 of this year
+ *   - last_week_start            → Monday 00:00 of previous week
+ *   - last_month_start           → 1st 00:00 of previous month
+ *   - last_quarter_start         → 1st 00:00 of previous quarter
+ *   - last_year_start            → Jan 1 00:00 of previous year
+ *
+ * Walks any plain-object / array structure recursively. Non-string values
+ * (and unknown tokens) are passed through untouched.
+ */
+export declare function resolveDateMacros<T = any>(filter: T, now?: Date): T;

package/dist/utils/date-macros.js

@@ -0,0 +1,102 @@
+/**
+ * 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.
+ */
+/**
+ * Resolve well-known relative-date placeholders inside a filter object so
+ * both server-side aggregation and client-side `find()` calls see a real
+ * ISO date string instead of a literal `{current_quarter_start}`.
+ *
+ * Supported tokens (case-sensitive, both `{token}` and `${token}` forms):
+ *   - today                      → start of today          (YYYY-MM-DD)
+ *   - now                        → current timestamp       (full ISO)
+ *   - current_week_start         → Monday 00:00 of this week
+ *   - current_month_start        → 1st 00:00 of this month
+ *   - current_quarter_start      → 1st 00:00 of this quarter
+ *   - current_year_start         → Jan 1 00:00 of this year
+ *   - last_week_start            → Monday 00:00 of previous week
+ *   - last_month_start           → 1st 00:00 of previous month
+ *   - last_quarter_start         → 1st 00:00 of previous quarter
+ *   - last_year_start            → Jan 1 00:00 of previous year
+ *
+ * Walks any plain-object / array structure recursively. Non-string values
+ * (and unknown tokens) are passed through untouched.
+ */
+export function resolveDateMacros(filter, now = new Date()) {
+    if (filter == null)
+        return filter;
+    const startOfDay = (d) => {
+        const x = new Date(d);
+        x.setHours(0, 0, 0, 0);
+        return x;
+    };
+    const isoDate = (d) => {
+        const x = startOfDay(d);
+        const yyyy = x.getFullYear();
+        const mm = String(x.getMonth() + 1).padStart(2, '0');
+        const dd = String(x.getDate()).padStart(2, '0');
+        return `${yyyy}-${mm}-${dd}`;
+    };
+    const startOfWeek = (d) => {
+        const x = startOfDay(d);
+        const day = x.getDay(); // 0=Sun, 1=Mon, ...
+        const diff = (day + 6) % 7; // distance back to Monday
+        x.setDate(x.getDate() - diff);
+        return x;
+    };
+    const startOfMonth = (d) => new Date(d.getFullYear(), d.getMonth(), 1);
+    const startOfQuarter = (d) => {
+        const q = Math.floor(d.getMonth() / 3);
+        return new Date(d.getFullYear(), q * 3, 1);
+    };
+    const startOfYear = (d) => new Date(d.getFullYear(), 0, 1);
+    const addMonths = (d, n) => new Date(d.getFullYear(), d.getMonth() + n, 1);
+    const macros = {
+        today: () => isoDate(now),
+        now: () => now.toISOString(),
+        current_week_start: () => isoDate(startOfWeek(now)),
+        current_month_start: () => isoDate(startOfMonth(now)),
+        current_quarter_start: () => isoDate(startOfQuarter(now)),
+        current_year_start: () => isoDate(startOfYear(now)),
+        last_week_start: () => {
+            const w = startOfWeek(now);
+            w.setDate(w.getDate() - 7);
+            return isoDate(w);
+        },
+        last_month_start: () => isoDate(addMonths(startOfMonth(now), -1)),
+        last_quarter_start: () => isoDate(addMonths(startOfQuarter(now), -3)),
+        last_year_start: () => isoDate(new Date(now.getFullYear() - 1, 0, 1)),
+    };
+    const tokenRe = /\$?\{([a-zA-Z_][a-zA-Z0-9_]*)\}/g;
+    const walk = (value) => {
+        if (value == null)
+            return value;
+        if (typeof value === 'string') {
+            const wholeMatch = value.match(/^\$?\{([a-zA-Z_][a-zA-Z0-9_]*)\}$/);
+            if (wholeMatch && macros[wholeMatch[1]])
+                return macros[wholeMatch[1]]();
+            let touched = false;
+            const replaced = value.replace(tokenRe, (m, tok) => {
+                if (macros[tok]) {
+                    touched = true;
+                    return macros[tok]();
+                }
+                return m;
+            });
+            return touched ? replaced : value;
+        }
+        if (Array.isArray(value))
+            return value.map(walk);
+        if (typeof value === 'object') {
+            const out = {};
+            for (const k of Object.keys(value))
+                out[k] = walk(value[k]);
+            return out;
+        }
+        return value;
+    };
+    return walk(filter);
+}

package/dist/utils/drill-down.d.ts

@@ -0,0 +1,91 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * Drill-down helpers shared by PivotTable and chart widgets.
+ *
+ * The functions here implement the **Style A (declarative)** drill-down
+ * protocol: a widget schema may carry an optional `drillDown` block, and
+ * when a user clicks a cell / bar / segment the widget builds a click
+ * payload (`event`) and asks these helpers to derive a filter + title for
+ * the drill-down drawer.
+ *
+ * ```jsonc
+ * "drillDown": {
+ *   "enabled": true,
+ *   "filter": { "stage": "${event.rowKey}", "lead_source": "${event.colKey}" },
+ *   "title":  "${event.rowLabel} × ${event.colLabel}"
+ * }
+ * ```
+ *
+ * The helpers are intentionally protocol-agnostic — any caller can
+ * synthesize an `event` object and rely on the same defaults / templating.
+ */
+import type { DrillDownConfig } from '@object-ui/types';
+/**
+ * Generic click payload. Pivots provide row/col, charts provide
+ * category/series. Extra fields are passed through verbatim so callers
+ * can reference them in templates.
+ */
+export interface DrillEvent {
+    /** Pivot: row field raw value. */
+    rowKey?: string;
+    /** Pivot: column field raw value. */
+    colKey?: string;
+    /** Pivot: human-readable row label. */
+    rowLabel?: string;
+    /** Pivot: human-readable column label. */
+    colLabel?: string;
+    /** Chart: x-axis / category value. */
+    category?: string;
+    /** Chart: human-readable label for the category (when raw differs from display). */
+    categoryLabel?: string;
+    /** Chart: series name (multi-series charts). */
+    series?: string;
+    /** Aggregated value at the click point. */
+    value?: number;
+    /** Pivot scope: which cell type was clicked. */
+    scope?: 'cell' | 'row' | 'column' | 'total';
+    /** Free-form pass-through (e.g. raw record reference). */
+    [key: string]: unknown;
+}
+/** Default field hints used to derive a filter when `config.filter` is omitted. */
+export interface DrillDefaults {
+    rowField?: string;
+    columnField?: string;
+    /** Chart group-by field (xAxisKey / aggregate.groupBy). */
+    groupByField?: string;
+}
+/**
+ * Substitute `${event.x}` placeholders in a string with values from the
+ * event payload. Unknown keys resolve to an empty string.
+ *
+ * Non-string values are coerced via `String(...)`. Returns the input
+ * unchanged when no placeholder is present.
+ */
+export declare function interpolate(template: string, event: DrillEvent): string;
+/**
+ * Compute the filter object passed to the drilled list view.
+ *
+ * Resolution order:
+ * 1. `config.filter` (interpolated against the event)
+ * 2. Defaults derived from `defaults`:
+ *    - `rowField` + event.rowKey  (pivot)
+ *    - `columnField` + event.colKey  (pivot)
+ *    - `groupByField` + event.category  (chart)
+ *
+ * Pivot scope shortcuts:
+ *   - scope === 'row'    → only rowField filter
+ *   - scope === 'column' → only columnField filter
+ *   - scope === 'total'  → empty filter (drill-through to the full set)
+ */
+export declare function computeDrillFilter(config: DrillDownConfig | undefined, event: DrillEvent, defaults?: DrillDefaults): Record<string, unknown>;
+/**
+ * Compute the drill-down title (for drawer/dialog header).
+ *
+ * Falls back to the most descriptive non-empty thing we know about the
+ * click point. Always returns a non-empty string.
+ */
+export declare function resolveDrillTitle(config: DrillDownConfig | undefined, event: DrillEvent, fallback?: string): string;
+/** Whether drill-down is enabled on a config (treats `{}` as enabled too). */
+export declare function isDrillEnabled(config: DrillDownConfig | undefined): boolean;

package/dist/utils/drill-down.js

@@ -0,0 +1,139 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * Drill-down helpers shared by PivotTable and chart widgets.
+ *
+ * The functions here implement the **Style A (declarative)** drill-down
+ * protocol: a widget schema may carry an optional `drillDown` block, and
+ * when a user clicks a cell / bar / segment the widget builds a click
+ * payload (`event`) and asks these helpers to derive a filter + title for
+ * the drill-down drawer.
+ *
+ * ```jsonc
+ * "drillDown": {
+ *   "enabled": true,
+ *   "filter": { "stage": "${event.rowKey}", "lead_source": "${event.colKey}" },
+ *   "title":  "${event.rowLabel} × ${event.colLabel}"
+ * }
+ * ```
+ *
+ * The helpers are intentionally protocol-agnostic — any caller can
+ * synthesize an `event` object and rely on the same defaults / templating.
+ */
+const TEMPLATE = /\$\{event\.([a-zA-Z0-9_]+)\}/g;
+/**
+ * Substitute `${event.x}` placeholders in a string with values from the
+ * event payload. Unknown keys resolve to an empty string.
+ *
+ * Non-string values are coerced via `String(...)`. Returns the input
+ * unchanged when no placeholder is present.
+ */
+export function interpolate(template, event) {
+    if (typeof template !== 'string' || template.indexOf('${event.') === -1) {
+        return template;
+    }
+    return template.replace(TEMPLATE, (_match, key) => {
+        const v = event[key];
+        if (v === undefined || v === null)
+            return '';
+        return String(v);
+    });
+}
+/**
+ * Recursively walk a filter object/value and replace `${event.*}` strings
+ * with the event values. Whole-string templates that resolve to a single
+ * event field preserve the original (typed) value — e.g. `"${event.value}"`
+ * stays a number — so backend filters can compare against the right type.
+ */
+function interpolateValue(value, event) {
+    if (typeof value === 'string') {
+        // Whole-string template (e.g. "${event.rowKey}") → keep typed value
+        const m = value.match(/^\$\{event\.([a-zA-Z0-9_]+)\}$/);
+        if (m) {
+            const raw = event[m[1]];
+            // Convert empty string sentinel back to null for SQL filter friendliness
+            if (raw === '')
+                return null;
+            return raw === undefined ? null : raw;
+        }
+        return interpolate(value, event);
+    }
+    if (Array.isArray(value)) {
+        return value.map(v => interpolateValue(v, event));
+    }
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = interpolateValue(v, event);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * Compute the filter object passed to the drilled list view.
+ *
+ * Resolution order:
+ * 1. `config.filter` (interpolated against the event)
+ * 2. Defaults derived from `defaults`:
+ *    - `rowField` + event.rowKey  (pivot)
+ *    - `columnField` + event.colKey  (pivot)
+ *    - `groupByField` + event.category  (chart)
+ *
+ * Pivot scope shortcuts:
+ *   - scope === 'row'    → only rowField filter
+ *   - scope === 'column' → only columnField filter
+ *   - scope === 'total'  → empty filter (drill-through to the full set)
+ */
+export function computeDrillFilter(config, event, defaults = {}) {
+    if (config?.filter) {
+        return interpolateValue(config.filter, event);
+    }
+    const out = {};
+    const { rowField, columnField, groupByField } = defaults;
+    const scope = event.scope ?? 'cell';
+    if (scope === 'total')
+        return out;
+    if ((scope === 'cell' || scope === 'row') && rowField && 'rowKey' in event) {
+        out[rowField] = event.rowKey === '' ? null : event.rowKey;
+    }
+    if ((scope === 'cell' || scope === 'column') && columnField && 'colKey' in event) {
+        out[columnField] = event.colKey === '' ? null : event.colKey;
+    }
+    if (groupByField && 'category' in event) {
+        out[groupByField] = event.category === '' ? null : event.category;
+    }
+    return out;
+}
+/**
+ * Compute the drill-down title (for drawer/dialog header).
+ *
+ * Falls back to the most descriptive non-empty thing we know about the
+ * click point. Always returns a non-empty string.
+ */
+export function resolveDrillTitle(config, event, fallback = 'Details') {
+    if (config?.title) {
+        const t = interpolate(config.title, event).trim();
+        if (t)
+            return t;
+    }
+    const parts = [];
+    if (event.rowLabel)
+        parts.push(event.rowLabel);
+    if (event.colLabel)
+        parts.push(event.colLabel);
+    if (event.categoryLabel)
+        parts.push(event.categoryLabel);
+    else if (event.category)
+        parts.push(event.category);
+    if (event.series)
+        parts.push(event.series);
+    return parts.length > 0 ? parts.join(' × ') : fallback;
+}
+/** Whether drill-down is enabled on a config (treats `{}` as enabled too). */
+export function isDrillEnabled(config) {
+    if (!config)
+        return false;
+    return config.enabled !== false;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/core",
-  "version": "4.0.7",
+  "version": "4.0.8",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -25,14 +25,14 @@
     }
   },
   "dependencies": {
-    "@objectstack/spec": "^4.0.4",
+    "@objectstack/spec": "^4.0.5",
     "lodash": "^4.18.1",
     "zod": "^4.4.3",
-    "@object-ui/types": "4.0.7"
+    "@object-ui/types": "4.0.8"
   },
   "devDependencies": {
     "typescript": "^6.0.3",
-    "vitest": "^4.1.5"
+    "vitest": "^4.1.6"
   },
   "keywords": [
     "objectui",