fix(spec): enforce ViewFilterRule operator enum with legacy-alias normalization

Replace the free-form `operator: z.string()` on ViewFilterRuleSchema with a
canonical `z.enum` (VIEW_FILTER_OPERATORS) wrapped in `z.preprocess` that folds
legacy shorthand/camelCase spellings (eq, gt, isNull, notEquals, …) to canonical
on parse. This surfaces a clean operator enum to JSON-Schema consumers (ObjectUI
SchemaForm renders a dropdown) and rejects genuinely unknown operators, while
already-stored metadata keeps validating and upgrades to one vocabulary.

- Export VIEW_FILTER_OPERATORS, ViewFilterOperator, VIEW_FILTER_OPERATOR_ALIASES
  and a normalizeFilterOperator() helper as the single source of truth.
- Pin `widget: 'filter-builder'` on the list view `filter` field in view.form.ts,
  matching dataset/page forms so the visual builder renders instead of a repeater.
- Canonicalize plugin-sharing sys_share_link filters (isNull -> is_null,
  isNotNull -> is_not_null), preserving null semantics.
- Keep the legacy string `sort` form (deprecation note only); retain the
  objectui#2601 regression fixture.
- Relative-date operators (this_quarter, …) are not filter-rule operators; tests
  updated to canonical operators and alias-normalization / unknown-rejection
  coverage added.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PwbhoMeqh33xFWq5M77QTJ

Author: claude

packages/plugins/plugin-sharing/src/objects/sys-share-link.object.ts

@@ -58,7 +58,7 @@ export const SysShareLink = ObjectSchema.create({
       label: 'Active',
       data: { provider: 'object', object: 'sys_share_link' },
       columns: ['object_name', 'record_id', 'permission', 'audience', 'expires_at', 'use_count', 'last_used_at'],
-      filter: [{ field: 'revoked_at', operator: 'isNull' }],
+      filter: [{ field: 'revoked_at', operator: 'is_null' }],
       sort: [{ field: 'created_at', order: 'desc' }],
       pagination: { pageSize: 100 },
     },
@@ -78,7 +78,7 @@ export const SysShareLink = ObjectSchema.create({
       label: 'Revoked',
       data: { provider: 'object', object: 'sys_share_link' },
       columns: ['object_name', 'record_id', 'revoked_at', 'created_by'],
-      filter: [{ field: 'revoked_at', operator: 'isNotNull' }],
+      filter: [{ field: 'revoked_at', operator: 'is_not_null' }],
       sort: [{ field: 'revoked_at', order: 'desc' }],
       pagination: { pageSize: 50 },
     },

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

@@ -37,7 +37,7 @@ export const viewForm = defineForm({
       description: 'What rows show and how users filter them.',
       fields: [
         { field: 'columns', type: 'repeater', required: true, helpText: 'Columns to display (field names from selected object)' },
-        { field: 'filter', type: 'repeater', helpText: 'Filter conditions' },
+        { field: 'filter', widget: 'filter-builder', dependsOn: 'data.object', helpText: 'Filter conditions — same visual builder as the list toolbar, with field-type-aware operators and value inputs' },
         { field: 'sort', type: 'repeater', helpText: 'Default sort order' },
         { field: 'searchableFields', widget: 'string-tags', helpText: 'Field names available for quick search' },
         { field: 'filterableFields', widget: 'string-tags', helpText: 'Field names available for filtering' },

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

@@ -734,7 +734,7 @@ describe('ViewSchema', () => {
             type: 'grid',
             columns: ['name', 'account_name', 'amount', 'stage', 'close_date'],
             filter: [
-              { field: 'close_date', operator: 'this_quarter' },
+              { field: 'close_date', operator: 'after', value: '2024-01-01' },
             ],
             sort: [{ field: 'amount', order: 'desc' }],
           },
@@ -2477,15 +2477,29 @@ describe('ViewFilterRuleSchema', () => {
 
   it('should accept a unary filter rule without value', () => {
     const rule = ViewFilterRuleSchema.parse({
-      field: 'close_date',
-      operator: 'this_quarter',
+      field: 'archived_at',
+      operator: 'is_empty',
     });
     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();
+    expect(() => ViewFilterRuleSchema.parse({ field: 'amount', operator: 'greater_than_or_equal', value: 1000 })).not.toThrow();
+  });
+
+  it('should normalize legacy operator aliases to canonical', () => {
+    expect(ViewFilterRuleSchema.parse({ field: 'amount', operator: 'gte', value: 1 }).operator).toBe('greater_than_or_equal');
+    expect(ViewFilterRuleSchema.parse({ field: 'amount', operator: 'gt', value: 1 }).operator).toBe('greater_than');
+    expect(ViewFilterRuleSchema.parse({ field: 'name', operator: 'eq', value: 'x' }).operator).toBe('equals');
+    expect(ViewFilterRuleSchema.parse({ field: 'name', operator: 'notEquals', value: 'x' }).operator).toBe('not_equals');
+    expect(ViewFilterRuleSchema.parse({ field: 'revoked_at', operator: 'isNull' }).operator).toBe('is_null');
+    expect(ViewFilterRuleSchema.parse({ field: 'tags', operator: 'nin', value: ['a'] }).operator).toBe('not_in');
+  });
+
+  it('should reject a genuinely unknown operator', () => {
+    expect(() => ViewFilterRuleSchema.parse({ field: 'close_date', operator: 'this_quarter' })).toThrow();
+    expect(() => ViewFilterRuleSchema.parse({ field: 'x', operator: 'totally_bogus' })).toThrow();
   });
 
   it('should accept array filter values (for IN operator)', () => {

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

@@ -55,6 +55,78 @@ export const ViewDataSchema = lazySchema(() => z.discriminatedUnion('provider',
   }),
 ]));
 
+/**
+ * Canonical filter operators for view filter rules.
+ *
+ * This is the SINGLE authoring vocabulary for `ViewFilterRule.operator`.
+ * Exposing it as an enum (rather than a free `z.string()`) lets JSON-Schema
+ * consumers — notably ObjectUI's SchemaForm — auto-render an operator
+ * dropdown, and rejects genuinely unknown operators at parse time.
+ *
+ * Unary operators (`is_empty`, `is_not_empty`, `is_null`, `is_not_null`) take
+ * no `value`. `before` / `after` are the date-friendly spellings of
+ * `less_than` / `greater_than`; `between` expects a two-element `value` array.
+ *
+ * Note: relative-date operators (`this_quarter`, `last_7_days`, …) are NOT
+ * filter-rule operators — they are date-range presets and live on dashboard
+ * date-range config (`DashboardFilterSchema.defaultRange`), not here.
+ */
+export const VIEW_FILTER_OPERATORS = [
+  'equals', 'not_equals',
+  'contains', 'not_contains',
+  'starts_with', 'ends_with',
+  'greater_than', 'less_than',
+  'greater_than_or_equal', 'less_than_or_equal',
+  'in', 'not_in',
+  'is_empty', 'is_not_empty',
+  'is_null', 'is_not_null',
+  'before', 'after', 'between',
+] as const;
+
+export type ViewFilterOperator = (typeof VIEW_FILTER_OPERATORS)[number];
+
+/**
+ * Legacy operator spellings normalized to the canonical vocabulary above.
+ *
+ * These are historical shorthand (`eq`, `gt`) and camelCase (`notEquals`,
+ * `greaterThan`) forms that older authoring tools and already-stored view
+ * metadata may still carry. They are folded to canonical on parse so every
+ * downstream consumer sees exactly one vocabulary — one strict contract, not
+ * N dialects. Deprecated: new producers MUST emit the canonical forms; these
+ * aliases are a migration bridge and may be dropped in a future major.
+ */
+export const VIEW_FILTER_OPERATOR_ALIASES: Record<string, ViewFilterOperator> = {
+  eq: 'equals',
+  ne: 'not_equals', neq: 'not_equals', notequals: 'not_equals', notEquals: 'not_equals',
+  notcontains: 'not_contains', notContains: 'not_contains',
+  startswith: 'starts_with', startsWith: 'starts_with',
+  endswith: 'ends_with', endsWith: 'ends_with',
+  gt: 'greater_than', greaterthan: 'greater_than', greaterThan: 'greater_than',
+  lt: 'less_than', lessthan: 'less_than', lessThan: 'less_than',
+  gte: 'greater_than_or_equal', greaterorequal: 'greater_than_or_equal',
+  greaterOrEqual: 'greater_than_or_equal', greaterThanOrEqual: 'greater_than_or_equal',
+  lte: 'less_than_or_equal', lessorequal: 'less_than_or_equal',
+  lessOrEqual: 'less_than_or_equal', lessThanOrEqual: 'less_than_or_equal',
+  nin: 'not_in', notin: 'not_in', notIn: 'not_in',
+  isempty: 'is_empty', isEmpty: 'is_empty',
+  isnotempty: 'is_not_empty', isNotEmpty: 'is_not_empty',
+  isnull: 'is_null', isNull: 'is_null',
+  isnotnull: 'is_not_null', isNotNull: 'is_not_null',
+};
+
+/**
+ * Fold a legacy operator spelling to its canonical form. Returns canonical
+ * operators unchanged, maps known aliases, and returns unknown input verbatim
+ * (so the enum's own validation reports it as invalid). Exported so producers
+ * and renderers can normalize stored metadata against the SAME canonical map
+ * the schema uses, instead of inventing a second dialect.
+ */
+export function normalizeFilterOperator(op: unknown): string {
+  if (typeof op !== 'string') return op as string;
+  if ((VIEW_FILTER_OPERATORS as readonly string[]).includes(op)) return op;
+  return VIEW_FILTER_OPERATOR_ALIASES[op] ?? VIEW_FILTER_OPERATOR_ALIASES[op.toLowerCase()] ?? op;
+}
+
 /**
  * View Filter Rule Schema
  * Standardized filter condition used in list views, tabs, and page-level filters.
@@ -64,16 +136,22 @@ export const ViewDataSchema = lazySchema(() => z.discriminatedUnion('provider',
  * ```ts
  * filter: [
  *   { field: 'status', operator: 'equals', value: 'active' },
- *   { field: 'close_date', operator: 'this_quarter' },
+ *   { field: 'close_date', operator: 'after', value: '2024-01-01' },
+ *   { field: 'archived_at', operator: 'is_empty' },
  * ]
  * ```
  */
 export const ViewFilterRuleSchema = lazySchema(() => 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) */
+  /**
+   * Filter operator (canonical vocabulary). Legacy shorthand/camelCase
+   * spellings (`eq`, `gt`, `isNull`, …) are accepted and normalized to
+   * canonical on parse.
+   */
+  operator: z.preprocess(normalizeFilterOperator, z.enum(VIEW_FILTER_OPERATORS))
+    .describe('Filter operator'),
+  /** Filter value (optional for unary operators like is_empty, is_null) */
   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'));
@@ -551,6 +629,14 @@ export const ListViewSchema = lazySchema(() => z.object({
     z.array(ListColumnSchema), // Enhanced: detailed column config
   ]).describe('Fields to display as columns'),
   filter: z.array(ViewFilterRuleSchema).optional().describe('Filter criteria (JSON Rules)'),
+  /**
+   * Sort order. Prefer the structured `{ field, order }[]` form.
+   *
+   * @deprecated The bare string form (`"field desc"`) is legacy and retained
+   * only for backward compatibility (it was the exact shape that crashed the
+   * renderer in objectui#2601 — kept covered by a live fixture). Removal will
+   * go through its own deprecation cycle; do not drop it here.
+   */
   sort: z.union([
     z.string(), //Legacy "field desc"
     z.array(z.object({