Add ViewFilterRuleSchema, unify filter types in view/page/component, add example-level strict validation tests

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

ROADMAP.md

@@ -99,7 +99,7 @@ This strategy ensures rapid iteration while maintaining a clear path to producti
 | Service Contracts | 27 |
 | Contracts Implemented | 13 (52%) |
 | Test Files | 229 |
-| Tests Passing | 6,445 / 6,445 |
+| Tests Passing | 6,456 / 6,456 |
 | `@deprecated` Items | 3 |
 | Protocol Domains | 15 (Data, UI, AI, API, Automation, Cloud, Contracts, Identity, Integration, Kernel, QA, Security, Shared, Studio, System) |
 
@@ -108,12 +108,15 @@ This strategy ensures rapid iteration while maintaining a clear path to producti
 | Item | Status | Details |
 |:---|:---:|:---|
 | `defineStack()` strict by default | ✅ | `strict: true` default since v3.0.2, validates schemas + cross-references |
-| `z.any()` elimination in UI protocol | ✅ | All `filter` fields → `FilterConditionSchema`, all `value` fields → typed unions |
+| `z.any()` elimination in UI protocol | ✅ | All `filter` fields → `FilterConditionSchema` or `ViewFilterRuleSchema`, all `value` fields → typed unions |
+| Filter format unification | ✅ | MongoDB-style filters use `FilterConditionSchema`, declarative view/tab filters use `ViewFilterRuleSchema` — `z.array(z.unknown())` eliminated |
 | Seed data → object cross-reference | ✅ | `validateCrossReferences` detects seed data referencing undefined objects |
-| Navigation → object/dashboard/page/report cross-reference | ✅ | App navigation items validated against defined metadata |
-| Negative validation tests (dashboard, page, report) | ✅ | Missing required fields, invalid enums, type violations all covered |
+| Navigation → object/dashboard/page/report cross-reference | ✅ | App navigation items validated against defined metadata (recursive group support) |
+| Negative validation tests (dashboard, page, report, view) | ✅ | Missing required fields, invalid enums, type violations, cross-reference errors all covered |
+| Example-level strict validation tests | ✅ | Todo-style and CRM-style full app configs validated in strict mode |
+| SSOT: types from Zod (`z.infer`) | ✅ | 135 UI types derived via `z.infer`, zero duplicate interfaces in `.zod.ts` files |
 | `z.any()` in data/filter.zod.ts (8 instances) | ✅ Justified | Runtime comparison operators (`$eq`, `$ne`, `$in`, `$nin`) accept any value type |
-| `z.unknown()` hardening in remaining schemas | 🟡 | `z.unknown()` used for extensible config/metadata fields — stricter composite schemas planned |
+| `z.unknown()` in extensibility fields | ✅ Justified | `properties`, `children`, `context`, `options`, `body` — inherently dynamic extensibility points |
 | DashboardWidget discriminated union by type | 🔴 | Planned — chart/metric/pivot subtypes with type-specific required fields |
 | CI lint rule rejecting new `z.any()` | 🔴 | Planned — eslint or custom lint rule to block `z.any()` additions |
 

packages/spec/src/stack.test.ts

@@ -960,3 +960,176 @@ describe('defineStack - Navigation Cross-Reference Validation', () => {
     expect(() => defineStack(config)).not.toThrow();
   });
 });
+
+// ============================================================================
+// Example-Level Strict Validation — mirrors examples/app-todo & examples/app-crm
+// ============================================================================
+
+describe('defineStack - Example-Level Strict Validation', () => {
+  it('should validate a Todo-style app config (strict mode)', () => {
+    const todoConfig = {
+      manifest: {
+        id: 'com.example.todo',
+        namespace: 'todo',
+        version: '2.0.0',
+        type: 'app' as const,
+        name: 'Todo Manager',
+        description: 'A comprehensive Todo app',
+      },
+      objects: [
+        {
+          name: 'task',
+          label: 'Task',
+          fields: {
+            subject: { type: 'text', label: 'Subject', required: true },
+            status: { type: 'select', label: 'Status', options: [
+              { value: 'not_started', label: 'Not Started' },
+              { value: 'in_progress', label: 'In Progress' },
+              { value: 'completed', label: 'Completed' },
+            ]},
+            priority: { type: 'select', label: 'Priority', options: [
+              { value: 'low', label: 'Low' },
+              { value: 'normal', label: 'Normal' },
+              { value: 'high', label: 'High' },
+            ]},
+            category: { type: 'text', label: 'Category' },
+            due_date: { type: 'date', label: 'Due Date' },
+          },
+        },
+      ],
+      data: [
+        {
+          object: 'task',
+          mode: 'upsert' as const,
+          externalId: 'subject',
+          records: [
+            { subject: 'Learn ObjectStack', status: 'completed', priority: 'high', category: 'Work' },
+            { subject: 'Build a cool app', status: 'in_progress', priority: 'normal', category: 'Work' },
+          ],
+        },
+      ],
+      dashboards: [
+        {
+          name: 'task_overview',
+          label: 'Task Overview',
+          widgets: [
+            { title: 'Total Tasks', type: 'metric', object: 'task', aggregate: 'count', layout: { x: 0, y: 0, w: 3, h: 2 } },
+            { title: 'By Status', type: 'pie', object: 'task', categoryField: 'status', aggregate: 'count', layout: { x: 3, y: 0, w: 6, h: 4 } },
+          ],
+        },
+      ],
+      apps: [
+        {
+          name: 'todo_app',
+          label: 'Todo Manager',
+          navigation: [
+            { id: 'nav_tasks', type: 'object' as const, label: 'Tasks', objectName: 'task' },
+            { id: 'nav_dashboard', type: 'dashboard' as const, label: 'Overview', dashboardName: 'task_overview' },
+          ],
+        },
+      ],
+    };
+    expect(() => defineStack(todoConfig, { strict: true })).not.toThrow();
+  });
+
+  it('should validate a CRM-style app config with seed data and reports (strict mode)', () => {
+    const crmConfig = {
+      manifest: {
+        id: 'com.example.crm',
+        namespace: 'crm',
+        version: '1.0.0',
+        type: 'app' as const,
+        name: 'Sales CRM',
+        description: 'Complete sales management solution',
+      },
+      objects: [
+        {
+          name: 'account',
+          label: 'Account',
+          fields: {
+            name: { type: 'text', label: 'Name', required: true },
+            industry: { type: 'text', label: 'Industry' },
+            annual_revenue: { type: 'number', label: 'Annual Revenue' },
+          },
+        },
+        {
+          name: 'opportunity',
+          label: 'Opportunity',
+          fields: {
+            name: { type: 'text', label: 'Name', required: true },
+            amount: { type: 'currency', label: 'Amount' },
+            stage: { type: 'select', label: 'Stage', options: [
+              { value: 'prospecting', label: 'Prospecting' },
+              { value: 'negotiation', label: 'Negotiation' },
+              { value: 'closed_won', label: 'Closed Won' },
+            ]},
+          },
+        },
+      ],
+      data: [
+        {
+          object: 'account',
+          mode: 'upsert' as const,
+          externalId: 'name',
+          records: [
+            { name: 'Acme Corp', industry: 'technology', annual_revenue: 5000000 },
+          ],
+        },
+      ],
+      reports: [
+        {
+          name: 'pipeline_report',
+          label: 'Pipeline Report',
+          objectName: 'opportunity',
+          type: 'summary' as const,
+          columns: [
+            { field: 'name' },
+            { field: 'amount', aggregate: 'sum' as const },
+          ],
+          groupingsDown: [{ field: 'stage' }],
+        },
+      ],
+      dashboards: [
+        {
+          name: 'sales_overview',
+          label: 'Sales Overview',
+          widgets: [
+            { title: 'Pipeline Value', type: 'metric', object: 'opportunity', valueField: 'amount', aggregate: 'sum', layout: { x: 0, y: 0, w: 4, h: 2 } },
+          ],
+        },
+      ],
+      apps: [
+        {
+          name: 'sales_crm',
+          label: 'Sales CRM',
+          icon: 'briefcase',
+          navigation: [
+            { id: 'nav_accounts', type: 'object' as const, label: 'Accounts', objectName: 'account' },
+            { id: 'nav_opportunities', type: 'object' as const, label: 'Opportunities', objectName: 'opportunity' },
+            { id: 'nav_dashboard', type: 'dashboard' as const, label: 'Sales Overview', dashboardName: 'sales_overview' },
+            { id: 'nav_report', type: 'report' as const, label: 'Pipeline', reportName: 'pipeline_report' },
+          ],
+        },
+      ],
+    };
+    expect(() => defineStack(crmConfig, { strict: true })).not.toThrow();
+  });
+
+  it('should reject CRM config with seed data referencing non-existent object', () => {
+    const badConfig = {
+      manifest: {
+        id: 'com.example.crm',
+        name: 'crm',
+        version: '1.0.0',
+        type: 'app' as const,
+      },
+      objects: [
+        { name: 'account', fields: { name: { type: 'text' } } },
+      ],
+      data: [
+        { object: 'contact', records: [{ name: 'John' }] },
+      ],
+    };
+    expect(() => defineStack(badConfig, { strict: true })).toThrow('contact');
+  });
+});

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

@@ -2,6 +2,7 @@
 
 import { z } from 'zod';
 import { FilterConditionSchema } from '../data/filter.zod';
+import { ViewFilterRuleSchema } from './view.zod';
 import { I18nLabelSchema, AriaPropsSchema } from './i18n.zod';
 import { FeedItemType, FeedFilterMode } from '../data/feed.zod';
 
@@ -77,7 +78,7 @@ export const RecordRelatedListProps = z.object({
     }))
   ]).optional().describe('Sort order for related records'),
   limit: z.number().int().positive().default(5).describe('Number of records to display initially'),
-  filter: z.array(z.unknown()).optional().describe('Additional filter criteria for related records'),
+  filter: z.array(ViewFilterRuleSchema).optional().describe('Additional filter criteria for related records'),
   title: I18nLabelSchema.optional().describe('Custom title for the related list'),
   showViewAll: z.boolean().default(true).describe('Show "View All" link to see all related records'),
   actions: z.array(z.string()).optional().describe('Action IDs available for related records'),

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

@@ -10,6 +10,7 @@ import {
   UserActionsConfigSchema,
   AppearanceConfigSchema,
   ViewTabSchema,
+  ViewFilterRuleSchema,
   AddRecordConfigSchema,
 } from './view.zod';
 
@@ -213,7 +214,7 @@ export const InterfacePageConfigSchema = z.object({
   /** Data binding */
   source: z.string().optional().describe('Source object name for the page'),
   levels: z.number().int().min(1).optional().describe('Number of hierarchy levels to display'),
-  filterBy: z.array(z.unknown()).optional().describe('Page-level filter criteria'),
+  filterBy: z.array(ViewFilterRuleSchema).optional().describe('Page-level filter criteria'),
 
   /** Appearance */
   appearance: AppearanceConfigSchema.optional().describe('Appearance and visualization configuration'),

packages/spec/src/ui/view.test.ts

@@ -26,6 +26,7 @@ import {
   UserActionsConfigSchema,
   AppearanceConfigSchema,
   ViewTabSchema,
+  ViewFilterRuleSchema,
   AddRecordConfigSchema,
   type View,
   type ListView,
@@ -2300,3 +2301,71 @@ describe('ListViewSchema — Airtable Interface parity fields', () => {
     expect(listView.allowPrinting).toBeUndefined();
   });
 });
+
+// ============================================================================
+// ViewFilterRuleSchema Tests
+// ============================================================================
+
+describe('ViewFilterRuleSchema', () => {
+  it('should accept a filter rule with field, operator, and value', () => {
+    const rule = ViewFilterRuleSchema.parse({
+      field: 'status',
+      operator: 'equals',
+      value: 'active',
+    });
+    expect(rule.field).toBe('status');
+    expect(rule.operator).toBe('equals');
+    expect(rule.value).toBe('active');
+  });
+
+  it('should accept a unary filter rule without value', () => {
+    const rule = ViewFilterRuleSchema.parse({
+      field: 'close_date',
+      operator: 'this_quarter',
+    });
+    expect(rule.value).toBeUndefined();
+  });
+
+  it('should accept boolean and number filter values', () => {
+    expect(() => ViewFilterRuleSchema.parse({ field: 'archived', operator: 'equals', value: false })).not.toThrow();
+    expect(() => ViewFilterRuleSchema.parse({ field: 'amount', operator: 'gte', value: 1000 })).not.toThrow();
+  });
+
+  it('should accept array filter values (for IN operator)', () => {
+    expect(() => ViewFilterRuleSchema.parse({
+      field: 'status',
+      operator: 'in',
+      value: ['active', 'pending'],
+    })).not.toThrow();
+  });
+
+  it('should reject filter rule without field', () => {
+    expect(() => ViewFilterRuleSchema.parse({ operator: 'equals', value: 'x' })).toThrow();
+  });
+
+  it('should reject filter rule without operator', () => {
+    expect(() => ViewFilterRuleSchema.parse({ field: 'status', value: 'x' })).toThrow();
+  });
+});
+
+describe('ListViewSchema filter field', () => {
+  it('should accept typed filter array', () => {
+    const view = ListViewSchema.parse({
+      type: 'grid',
+      columns: ['name', 'status'],
+      filter: [
+        { field: 'status', operator: 'equals', value: 'active' },
+        { field: 'archived', operator: 'equals', value: false },
+      ],
+    });
+    expect(view.filter).toHaveLength(2);
+  });
+
+  it('should reject filter with non-object entries', () => {
+    expect(() => ListViewSchema.parse({
+      type: 'grid',
+      columns: ['name'],
+      filter: ['invalid_string'],
+    })).toThrow();
+  });
+});

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

@@ -44,6 +44,31 @@ export const ViewDataSchema = z.discriminatedUnion('provider', [
   }),
 ]);
 
+/**
+ * View Filter Rule Schema
+ * Standardized filter condition used in list views, tabs, and page-level filters.
+ * Uses a declarative array-of-objects format: [{ field, operator, value }].
+ *
+ * @example
+ * ```ts
+ * filter: [
+ *   { field: 'status', operator: 'equals', value: 'active' },
+ *   { field: 'close_date', operator: 'this_quarter' },
+ * ]
+ * ```
+ */
+export const ViewFilterRuleSchema = z.object({
+  /** Field name to filter on */
+  field: z.string().describe('Field name to filter on'),
+  /** Filter operator */
+  operator: z.string().describe('Filter operator (e.g. equals, not_equals, contains, this_quarter)'),
+  /** Filter value (optional for unary operators like is_null, this_quarter) */
+  value: z.union([z.string(), z.number(), z.boolean(), z.null(), z.array(z.union([z.string(), z.number()]))])
+    .optional().describe('Filter value'),
+}).describe('View filter rule');
+
+export type ViewFilterRule = z.infer<typeof ViewFilterRuleSchema>;
+
 /**
  * Column Summary Function Schema
  * Aggregation function for column footer (Airtable-style column summaries)
@@ -231,7 +256,7 @@ export const ViewTabSchema = z.object({
   label: I18nLabelSchema.optional().describe('Display label'),
   icon: z.string().optional().describe('Tab icon name'),
   view: z.string().optional().describe('Referenced list view name from listViews'),
-  filter: z.array(z.unknown()).optional().describe('Tab-specific filter criteria'),
+  filter: z.array(ViewFilterRuleSchema).optional().describe('Tab-specific filter criteria'),
   order: z.number().int().min(0).optional().describe('Tab display order'),
   pinned: z.boolean().default(false).describe('Pin tab (cannot be removed by users)'),
   isDefault: z.boolean().default(false).describe('Set as the default active tab'),
@@ -360,7 +385,7 @@ export const ListViewSchema = z.object({
     z.array(z.string()), // Legacy: simple field names
     z.array(ListColumnSchema), // Enhanced: detailed column config
   ]).describe('Fields to display as columns'),
-  filter: z.array(z.unknown()).optional().describe('Filter criteria (JSON Rules)'),
+  filter: z.array(ViewFilterRuleSchema).optional().describe('Filter criteria (JSON Rules)'),
   sort: z.union([
     z.string(), //Legacy "field desc"
     z.array(z.object({
@@ -378,7 +403,8 @@ export const ListViewSchema = z.object({
     field: z.string().describe('Field name to filter by'),
     label: z.string().optional().describe('Display label for the chip'),
     operator: z.enum(['equals', 'not_equals', 'contains', 'in', 'is_null', 'is_not_null']).default('equals').describe('Filter operator'),
-    value: z.unknown().optional().describe('Preset filter value'),
+    value: z.union([z.string(), z.number(), z.boolean(), z.null(), z.array(z.union([z.string(), z.number()]))])
+      .optional().describe('Preset filter value'),
   })).optional().describe('One-click filter chips for quick record filtering'),
 
   /** Grid Features */