Merge pull request #811 from objectstack-ai/copilot/add-conditional-formatting-support

Author: hotlong

ROADMAP.md

@@ -737,7 +737,7 @@ The `FlowDesigner` is a canvas-based flow editor that bridges the gap between th
 
 **P1 — Structural Alignment:**
 - [x] `quickFilters` structure reconciliation: Auto-normalizes spec `{ field, operator, value }` format into ObjectUI `{ id, label, filters[] }` format. Both formats supported simultaneously. Dual-format type union (`QuickFilterItem = ObjectUIQuickFilterItem | SpecQuickFilterItem`) exported from `@object-ui/types`. Standalone `normalizeQuickFilter()` / `normalizeQuickFilters()` adapter functions in `@object-ui/core`. Bridge (`list-view.ts`) normalizes at spec→SchemaNode transform time. Spec shorthand operators (`eq`, `ne`, `gt`, `gte`, `lt`, `lte`) mapped to ObjectStack AST operators. Mixed-format arrays handled transparently.
-- [x] `conditionalFormatting` expression reconciliation: Supports spec `{ condition, style }` format alongside ObjectUI field/operator/value rules. `condition` is treated as alias for `expression`, `style` object merged into CSS properties.
+- [x] `conditionalFormatting` expression reconciliation: Supports spec `{ condition, style }` format alongside ObjectUI field/operator/value rules. Dual-format type union (`ConditionalFormattingRule = ObjectUIConditionalFormattingRule | SpecConditionalFormattingRule`) exported from `@object-ui/types`. Zod validator updated with `z.union()` for both formats. `evaluatePlainCondition()` convenience function in `@object-ui/core` for safe plain/template expression evaluation with record context. Plain expressions (e.g., `status == 'overdue'`) evaluated directly without `${}` wrapper; record fields spread into evaluator context for direct field references alongside `data.` namespace. Mixed-format arrays handled transparently.
 - [x] `exportOptions` schema reconciliation: Accepts both spec `string[]` format (e.g., `['csv', 'xlsx']`) and ObjectUI object format `{ formats, maxRecords, includeHeaders, fileNamePrefix }`.
 - [x] Column `pinned`: `pinned` property added to ListViewSchema column type. Bridge passes through to ObjectGrid which supports `frozenColumns`. ObjectGrid reorders columns (left-pinned first, right-pinned last with sticky CSS). Zod schema updated with `pinned` field. `useColumnSummary` hook created.
 - [x] Column `summary`: `summary` property added to ListViewSchema column type. Bridge passes through for aggregation rendering. ObjectGrid renders summary footer with count/sum/avg/min/max aggregations via `useColumnSummary` hook. Zod schema updated with `summary` field.

packages/core/src/evaluator/ExpressionEvaluator.ts

@@ -291,3 +291,25 @@ export function evaluateCondition(
   const evaluator = new ExpressionEvaluator(context, globalCache, globalFormulas);
   return evaluator.evaluateCondition(condition);
 }
+
+/**
+ * Convenience function to evaluate a plain condition string against a data record.
+ * Supports both template expressions (e.g., '${data.amount > 1000}') and
+ * plain expressions (e.g., "status == 'overdue'").
+ * Record fields are available both directly (status) and namespaced (data.status).
+ */
+export function evaluatePlainCondition(
+  condition: string,
+  record: Record<string, any>
+): boolean {
+  const evaluator = new ExpressionEvaluator({ ...record, data: record }, globalCache, globalFormulas);
+  try {
+    const isTemplate = /\$\{/.test(condition);
+    const result = isTemplate
+      ? evaluator.evaluate(condition, { throwOnError: true })
+      : evaluator.evaluateExpression(condition);
+    return result === true;
+  } catch {
+    return false;
+  }
+}

packages/core/src/evaluator/__tests__/ExpressionEvaluator.test.ts

@@ -7,7 +7,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
-import { ExpressionEvaluator, evaluateExpression, evaluateCondition } from '../ExpressionEvaluator';
+import { ExpressionEvaluator, evaluateExpression, evaluateCondition, evaluatePlainCondition } from '../ExpressionEvaluator';
 import { ExpressionContext } from '../ExpressionContext';
 
 describe('ExpressionContext', () => {
@@ -99,3 +99,33 @@ describe('ExpressionEvaluator', () => {
     });
   });
 });
+
+describe('evaluatePlainCondition', () => {
+  it('should evaluate a plain condition with direct field references', () => {
+    expect(evaluatePlainCondition("status == 'overdue'", { status: 'overdue' })).toBe(true);
+    expect(evaluatePlainCondition("status == 'overdue'", { status: 'active' })).toBe(false);
+  });
+
+  it('should evaluate numeric comparisons', () => {
+    expect(evaluatePlainCondition('amount > 1000', { amount: 2500 })).toBe(true);
+    expect(evaluatePlainCondition('amount > 1000', { amount: 500 })).toBe(false);
+  });
+
+  it('should evaluate compound conditions', () => {
+    expect(evaluatePlainCondition("amount > 1000 && status === 'urgent'", { amount: 2000, status: 'urgent' })).toBe(true);
+    expect(evaluatePlainCondition("amount > 1000 && status === 'urgent'", { amount: 2000, status: 'normal' })).toBe(false);
+  });
+
+  it('should support data.field references in template expressions', () => {
+    expect(evaluatePlainCondition('${data.amount > 1000}', { amount: 2000 })).toBe(true);
+    expect(evaluatePlainCondition('${data.amount > 1000}', { amount: 500 })).toBe(false);
+  });
+
+  it('should return false for invalid expressions', () => {
+    expect(evaluatePlainCondition('!!!invalidSyntax', { status: 'ok' })).toBe(false);
+  });
+
+  it('should return false for non-boolean results', () => {
+    expect(evaluatePlainCondition('status', { status: 'active' })).toBe(false);
+  });
+});

packages/plugin-list/src/ListView.tsx

@@ -19,7 +19,7 @@ import { SchemaRenderer, useNavigationOverlay } from '@object-ui/react';
 import { useDensityMode } from '@object-ui/react';
 import type { ListViewSchema } from '@object-ui/types';
 import { usePullToRefresh } from '@object-ui/mobile';
-import { ExpressionEvaluator, normalizeQuickFilters } from '@object-ui/core';
+import { evaluatePlainCondition, normalizeQuickFilters } from '@object-ui/core';
 import { useObjectTranslation } from '@object-ui/i18n';
 
 export interface ListViewProps {
@@ -139,20 +139,19 @@ export function evaluateConditionalFormatting(
   for (const rule of rules) {
     let match = false;
 
-    // Normalize: spec uses 'condition' as alias for 'expression'
-    const expression = rule.expression || rule.condition;
+    // Determine expression: spec uses 'condition', ObjectUI uses 'expression'
+    const expression =
+      ('condition' in rule ? rule.condition : undefined)
+      || ('expression' in rule ? rule.expression : undefined)
+      || undefined;
 
-    // Expression-based evaluation (L2 feature) using safe ExpressionEvaluator
+    // Expression-based evaluation using safe ExpressionEvaluator
+    // Supports both template expressions (${data.field > value}) and
+    // plain Spec expressions (field == 'value').
     if (expression) {
-      try {
-        const evaluator = new ExpressionEvaluator({ data: record });
-        const result = evaluator.evaluate(expression, { throwOnError: true });
-        match = result === true;
-      } catch {
-        match = false;
-      }
-    } else if (rule.field && rule.operator) {
-      // Standard field/operator/value evaluation
+      match = evaluatePlainCondition(expression, record as Record<string, any>);
+    } else if ('field' in rule && 'operator' in rule && rule.field && rule.operator) {
+      // Standard field/operator/value evaluation (ObjectUI format)
       const fieldValue = record[rule.field];
       switch (rule.operator) {
         case 'equals':
@@ -179,10 +178,10 @@ export function evaluateConditionalFormatting(
     if (match) {
       // Build style: spec 'style' object is base, individual properties override
       const style: React.CSSProperties = {};
-      if (rule.style) Object.assign(style, rule.style);
-      if (rule.backgroundColor) style.backgroundColor = rule.backgroundColor;
-      if (rule.textColor) style.color = rule.textColor;
-      if (rule.borderColor) style.borderColor = rule.borderColor;
+      if ('style' in rule && rule.style) Object.assign(style, rule.style);
+      if ('backgroundColor' in rule && rule.backgroundColor) style.backgroundColor = rule.backgroundColor;
+      if ('textColor' in rule && rule.textColor) style.color = rule.textColor;
+      if ('borderColor' in rule && rule.borderColor) style.borderColor = rule.borderColor;
       return style;
     }
   }

packages/plugin-list/src/__tests__/ConditionalFormatting.test.ts

@@ -141,6 +141,63 @@ describe('evaluateConditionalFormatting', () => {
     });
   });
 
+  // =========================================================================
+  // Spec expression format (plain condition + style object)
+  // =========================================================================
+  describe('spec expression format', () => {
+    it('evaluates a plain condition string via "condition" field', () => {
+      const result = evaluateConditionalFormatting(
+        { status: 'overdue' },
+        [{ condition: "status == 'overdue'", style: { backgroundColor: 'red' } }],
+      );
+      expect(result).toEqual({ backgroundColor: 'red' });
+    });
+
+    it('evaluates a numeric comparison in plain condition', () => {
+      const result = evaluateConditionalFormatting(
+        { amount: 2500 },
+        [{ condition: 'amount > 1000', style: { backgroundColor: '#fee2e2', color: '#991b1b' } }],
+      );
+      expect(result).toEqual({ backgroundColor: '#fee2e2', color: '#991b1b' });
+    });
+
+    it('returns empty when plain condition does not match', () => {
+      const result = evaluateConditionalFormatting(
+        { status: 'active' },
+        [{ condition: "status == 'overdue'", style: { backgroundColor: 'red' } }],
+      );
+      expect(result).toEqual({});
+    });
+
+    it('supports compound conditions with && operator', () => {
+      const result = evaluateConditionalFormatting(
+        { amount: 2000, status: 'urgent' },
+        [{ condition: "amount > 1000 && status === 'urgent'", style: { backgroundColor: '#fee' } }],
+      );
+      expect(result).toEqual({ backgroundColor: '#fee' });
+    });
+
+    it('merges style with individual color properties', () => {
+      const result = evaluateConditionalFormatting(
+        { status: 'overdue' },
+        [{
+          condition: "status == 'overdue'",
+          style: { fontWeight: 'bold' },
+          backgroundColor: '#f00',
+        }],
+      );
+      expect(result).toEqual({ fontWeight: 'bold', backgroundColor: '#f00' });
+    });
+
+    it('does not throw on invalid plain condition', () => {
+      const result = evaluateConditionalFormatting(
+        { status: 'ok' },
+        [{ condition: '!!!invalidSyntax', style: { backgroundColor: 'red' } }],
+      );
+      expect(result).toEqual({});
+    });
+  });
+
   // =========================================================================
   // Mixed rules (expression + standard) – first match wins
   // =========================================================================
@@ -188,6 +245,29 @@ describe('evaluateConditionalFormatting', () => {
       );
       expect(result).toEqual({ backgroundColor: '#operator_match' });
     });
+
+    it('handles mixed spec condition + ObjectUI field rules', () => {
+      const result = evaluateConditionalFormatting(
+        { status: 'overdue', priority: 'low' },
+        [
+          { condition: "status == 'overdue'", style: { backgroundColor: 'red' } },
+          { field: 'priority', operator: 'equals', value: 'low', backgroundColor: '#ccc' },
+        ],
+      );
+      // First matching rule wins
+      expect(result).toEqual({ backgroundColor: 'red' });
+    });
+
+    it('falls through non-matching spec condition to ObjectUI field rule', () => {
+      const result = evaluateConditionalFormatting(
+        { status: 'active', priority: 'low' },
+        [
+          { condition: "status == 'overdue'", style: { backgroundColor: 'red' } },
+          { field: 'priority', operator: 'equals', value: 'low', backgroundColor: '#ccc' },
+        ],
+      );
+      expect(result).toEqual({ backgroundColor: '#ccc' });
+    });
   });
 
   // =========================================================================

packages/types/src/index.ts

@@ -304,6 +304,10 @@ export type {
   ObjectUIQuickFilterItem,
   SpecQuickFilterItem,
   QuickFilterItem,
+  // ConditionalFormatting dual-format types
+  ObjectUIConditionalFormattingRule,
+  SpecConditionalFormattingRule,
+  ConditionalFormattingRule,
   // Component schemas
   ObjectMapSchema,
   ObjectGanttSchema,

packages/types/src/objectql.ts

@@ -207,6 +207,49 @@ export interface SpecQuickFilterItem {
  */
 export type QuickFilterItem = ObjectUIQuickFilterItem | SpecQuickFilterItem;
 
+// ============================================================================
+// ConditionalFormatting Types — Dual-format support
+// ============================================================================
+
+/**
+ * ObjectUI-native ConditionalFormatting rule.
+ * Uses field/operator/value for declarative comparisons.
+ */
+export interface ObjectUIConditionalFormattingRule {
+  /** Field name to evaluate */
+  field: string;
+  /** Comparison operator */
+  operator: 'equals' | 'not_equals' | 'contains' | 'greater_than' | 'less_than' | 'in';
+  /** Value to compare against */
+  value: unknown;
+  /** CSS-compatible background color */
+  backgroundColor?: string;
+  /** CSS-compatible text color */
+  textColor?: string;
+  /** CSS-compatible border color */
+  borderColor?: string;
+  /** Template expression override (e.g., '${data.amount > 1000}') */
+  expression?: string;
+}
+
+/**
+ * Spec-format ConditionalFormatting rule (from @objectstack/spec).
+ * Uses a plain expression string with a style map.
+ * Automatically evaluated at runtime via ExpressionEvaluator.
+ */
+export interface SpecConditionalFormattingRule {
+  /** Plain condition expression (e.g., "status == 'overdue'") or template expression (e.g., "${data.amount > 1000}") */
+  condition: string;
+  /** Style map to apply when condition matches (e.g., { backgroundColor: '#fee2e2', color: '#991b1b' }) */
+  style: Record<string, string>;
+}
+
+/**
+ * Union type for ConditionalFormatting rules — accepts both ObjectUI and Spec formats.
+ * Rules are evaluated in order; first matching rule wins.
+ */
+export type ConditionalFormattingRule = ObjectUIConditionalFormattingRule | SpecConditionalFormattingRule;
+
 /**
  * ObjectGrid Schema
  * A specialized grid component that automatically fetches and displays data from ObjectQL objects.
@@ -525,14 +568,9 @@ export interface ObjectGridSchema extends BaseSchema {
   /**
    * Conditional formatting rules for row/cell styling.
    * Aligned with @objectstack/spec ListViewSchema.conditionalFormatting.
-   * Uses expression-based conditions with style maps.
+   * Supports both ObjectUI field/operator/value rules and Spec expression-based { condition, style } rules.
    */
-  conditionalFormatting?: Array<{
-    /** Expression-based condition (e.g., '${data.amount > 1000}') */
-    condition: string;
-    /** Style map (e.g., { backgroundColor: '#fee2e2', textColor: '#991b1b' }) */
-    style: Record<string, string>;
-  }>;
+  conditionalFormatting?: ConditionalFormattingRule[];
 
   /**
    * Enable virtual scrolling for large datasets.
@@ -1193,16 +1231,9 @@ export interface NamedListView {
     formView?: string;
   };
 
-  /** Conditional formatting rules */
-  conditionalFormatting?: Array<{
-    field: string;
-    operator: 'equals' | 'not_equals' | 'contains' | 'greater_than' | 'less_than' | 'in';
-    value: unknown;
-    backgroundColor?: string;
-    textColor?: string;
-    borderColor?: string;
-    expression?: string;
-  }>;
+  /** Conditional formatting rules.
+   * Supports both ObjectUI field/operator/value rules and Spec expression-based { condition, style } rules. */
+  conditionalFormatting?: ConditionalFormattingRule[];
 
   /** Quick filter buttons for predefined filter presets.
    * Supports both ObjectUI format and Spec format (auto-converted at runtime). */
@@ -1491,26 +1522,7 @@ export interface ListViewSchema extends BaseSchema {
    * Rules are evaluated in order; first matching rule wins.
    * Supports both ObjectUI field/operator/value rules and spec expression-based { condition, style } rules.
    */
-  conditionalFormatting?: Array<{
-    /** Field to evaluate (ObjectUI format) */
-    field?: string;
-    /** Comparison operator (ObjectUI format) */
-    operator?: 'equals' | 'not_equals' | 'contains' | 'greater_than' | 'less_than' | 'in';
-    /** Value to compare against (ObjectUI format) */
-    value?: unknown;
-    /** CSS-compatible background color (e.g., '#fee2e2', 'rgb(254,226,226)') */
-    backgroundColor?: string;
-    /** CSS-compatible text color */
-    textColor?: string;
-    /** CSS-compatible border color */
-    borderColor?: string;
-    /** Expression-based condition (e.g., '${data.amount > 1000 && data.status === "urgent"}'). Overrides field/operator/value when provided. */
-    expression?: string;
-    /** Spec expression-based condition string (alias for expression) */
-    condition?: string;
-    /** Spec style object (e.g., { backgroundColor: '#fee2e2', color: '#991b1b' }) */
-    style?: Record<string, string>;
-  }>;
+  conditionalFormatting?: ConditionalFormattingRule[];
 
   /**
    * Enable inline editing for list view fields.

packages/types/src/zod/objectql.zod.ts

@@ -320,15 +320,21 @@ export const ListViewSchema = BaseSchema.extend({
     mode: z.string().optional(),
     formView: z.string().optional(),
   }).optional().describe('Add record configuration'),
-  conditionalFormatting: z.array(z.object({
-    field: z.string(),
-    operator: z.enum(['equals', 'not_equals', 'contains', 'greater_than', 'less_than', 'in']),
-    value: z.any(),
-    backgroundColor: z.string().optional(),
-    textColor: z.string().optional(),
-    borderColor: z.string().optional(),
-    expression: z.string().optional(),
-  })).optional().describe('Conditional formatting rules'),
+  conditionalFormatting: z.array(z.union([
+    z.object({
+      field: z.string(),
+      operator: z.enum(['equals', 'not_equals', 'contains', 'greater_than', 'less_than', 'in']),
+      value: z.any(),
+      backgroundColor: z.string().optional(),
+      textColor: z.string().optional(),
+      borderColor: z.string().optional(),
+      expression: z.string().optional(),
+    }),
+    z.object({
+      condition: z.string(),
+      style: z.record(z.string(), z.string()),
+    }),
+  ])).optional().describe('Conditional formatting rules'),
   quickFilters: z.array(z.object({
     id: z.string(),
     label: z.string(),