Merge pull request #749 from objectstack-ai/copilot/update-spec-ui-config

Author: hotlong

ROADMAP.md

@@ -98,7 +98,7 @@ This strategy ensures rapid iteration while maintaining a clear path to producti
 | Service Contracts | 25 |
 | Contracts Implemented | 13 (52%) |
 | Test Files | 199 |
-| Tests Passing | 5,468 / 5,468 |
+| Tests Passing | 5,805 / 5,805 |
 | `@deprecated` Items | 3 |
 | Protocol Domains | 15 (Data, UI, AI, API, Automation, Cloud, Contracts, Identity, Integration, Kernel, QA, Security, Shared, Studio, System) |
 
@@ -175,7 +175,7 @@ business/custom objects, aligning with industry best practices (e.g., ServiceNow
 
 - [x] **Data Protocol** — Object, Field (35+ types), Query, Filter, Validation, Hook, Datasource, Dataset, Analytics, Document, Storage Name Mapping (`tableName`/`columnName`), Feed & Activity Timeline (FeedItem, Comment, Mention, Reaction, FieldChange), Record Subscription (notification channels)
 - [x] **Driver Specifications** — Memory, PostgreSQL, MongoDB driver schemas + SQL/NoSQL abstractions
-- [x] **UI Protocol** — View (List/Form/Kanban/Calendar/Gantt), App, Dashboard, Report, Action, Page (16 types), Chart, Widget, Theme, Animation, DnD, Touch, Keyboard, Responsive, Offline, Notification, i18n, Content Elements, Enhanced Activity Timeline (`RecordActivityProps` unified timeline, `RecordChatterProps` sidebar/drawer), Unified Navigation Protocol (`NavigationItem` as single source of truth with 7 types: object/dashboard/page/url/report/action/group; `NavigationArea` for business domain partitioning; `order`/`badge`/`requiredPermissions` on all nav items)
+- [x] **UI Protocol** — View (List/Form/Kanban/Calendar/Gantt), App, Dashboard, Report, Action, Page (16 types), Chart, Widget, Theme, Animation, DnD, Touch, Keyboard, Responsive, Offline, Notification, i18n, Content Elements, Enhanced Activity Timeline (`RecordActivityProps` unified timeline, `RecordChatterProps` sidebar/drawer), Unified Navigation Protocol (`NavigationItem` as single source of truth with 7 types: object/dashboard/page/url/report/action/group; `NavigationArea` for business domain partitioning; `order`/`badge`/`requiredPermissions` on all nav items), Airtable Interface Parity (`UserActionsConfig`, `AppearanceConfig`, `ViewTab`, `AddRecordConfig`, `InterfacePageConfig`, `showRecordCount`, `allowPrinting`)
 - [x] **System Protocol** — Manifest, Auth Config, Cache, Logging, Metrics, Tracing, Audit, Encryption, Masking, Migration, Tenant, Translation, Search Engine, HTTP Server, Worker, Job, Object Storage, Notification, Message Queue, Registry Config, Collaboration, Compliance, Change Management, Disaster Recovery, License, Security Context, Core Services, SystemObjectName/SystemFieldName Constants, StorageNameMapping Utilities
 - [x] **Automation Protocol** — Flow (autolaunched/screen/schedule), Workflow, State Machine, Trigger Registry, Approval, ETL, Sync, Webhook
 - [x] **AI Protocol** — Agent, Agent Action, Conversation, Cost, MCP, Model Registry, NLQ, Orchestration, Predictive, RAG Pipeline, Runtime Ops, Feedback Loop, DevOps Agent, Plugin Development
@@ -465,6 +465,20 @@ business/custom objects, aligning with industry best practices (e.g., ServiceNow
 - [ ] Real-time collaborative page editing
 - [ ] Page analytics — page views, element interactions, user engagement
 
+#### Phase E: Interface Parity — User Actions, Appearance & Tabs (v3.x) ✅
+
+> Aligns Spec UI configuration with Airtable Interface capabilities.
+
+- [x] `UserActionsConfigSchema` — Declarative toggles for sort/search/filter/rowHeight/addRecordForm/buttons in view toolbar (`src/ui/view.zod.ts`)
+- [x] `AppearanceConfigSchema` — showDescription toggle and allowedVisualizations whitelist (`src/ui/view.zod.ts`)
+- [x] `VisualizationTypeSchema` — Enum of switchable visualization types (grid/kanban/gallery/calendar/timeline/gantt/map) (`src/ui/view.zod.ts`)
+- [x] `ViewTabSchema` — Multi-tab view interface with order, icon, pinned, isDefault, visible (`src/ui/view.zod.ts`)
+- [x] `AddRecordConfigSchema` — Add record entry point with position/mode/formView (`src/ui/view.zod.ts`)
+- [x] `showRecordCount` — Boolean on `ListViewSchema` for record count display (`src/ui/view.zod.ts`)
+- [x] `allowPrinting` — Boolean on `ListViewSchema` for print capability (`src/ui/view.zod.ts`)
+- [x] `InterfacePageConfigSchema` — Page-level interface configuration (source, levels, filterBy, appearance, userFilters, userActions, addRecord, showRecordCount, allowPrinting) (`src/ui/page.zod.ts`)
+- [x] `PageSchema.interfaceConfig` — Optional interface config on pages for Airtable-style declarative page setup (`src/ui/page.zod.ts`)
+
 ### 8.2 Dashboard Enhancement — Airtable Dashboard Parity
 
 > See [Airtable Dashboard Gap Analysis](content/docs/guides/airtable-dashboard-analysis.mdx) for the full evaluation and implementation examples.

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

@@ -8,11 +8,13 @@ import {
   ElementDataSourceSchema,
   BlankPageLayoutSchema,
   PageVariableSchema,
+  InterfacePageConfigSchema,
   type Page,
   type PageComponent,
   type PageRegion,
   type ElementDataSource,
   type RecordReviewConfig,
+  type InterfacePageConfig,
 } from './page.zod';
 
 describe('PageComponentSchema', () => {
@@ -948,3 +950,148 @@ describe('Page end-to-end', () => {
     expect(page.object).toBe('order');
   });
 });
+
+// ---------------------------------------------------------------------------
+// InterfacePageConfigSchema — Airtable Interface parity
+// ---------------------------------------------------------------------------
+describe('InterfacePageConfigSchema', () => {
+  it('should accept empty config', () => {
+    const config: InterfacePageConfig = InterfacePageConfigSchema.parse({});
+    expect(config).toBeDefined();
+  });
+
+  it('should accept full interface page config', () => {
+    const config = InterfacePageConfigSchema.parse({
+      source: 'customers',
+      levels: 1,
+      filterBy: [{ field: 'status', operator: 'equals', value: 'active' }],
+      appearance: {
+        showDescription: true,
+        allowedVisualizations: ['grid', 'gallery', 'kanban'],
+      },
+      userFilters: {
+        elements: ['grid', 'gallery', 'kanban'],
+        tabs: [
+          { name: 'my_customers', label: 'my customers', isDefault: true },
+          { name: 'all_records', label: 'All records' },
+        ],
+      },
+      userActions: {
+        sort: true,
+        search: true,
+        filter: true,
+        rowHeight: true,
+        addRecordForm: false,
+        buttons: [],
+      },
+      addRecord: {
+        enabled: true,
+        position: 'bottom',
+        mode: 'inline',
+      },
+      showRecordCount: true,
+      allowPrinting: true,
+    });
+
+    expect(config.source).toBe('customers');
+    expect(config.levels).toBe(1);
+    expect(config.appearance?.allowedVisualizations).toHaveLength(3);
+    expect(config.userFilters?.tabs).toHaveLength(2);
+    expect(config.userActions?.sort).toBe(true);
+    expect(config.showRecordCount).toBe(true);
+    expect(config.allowPrinting).toBe(true);
+  });
+
+  it('should accept config with only source and levels', () => {
+    const config = InterfacePageConfigSchema.parse({
+      source: 'orders',
+      levels: 2,
+    });
+    expect(config.source).toBe('orders');
+    expect(config.levels).toBe(2);
+  });
+
+  it('should reject levels < 1', () => {
+    expect(() => InterfacePageConfigSchema.parse({
+      levels: 0,
+    })).toThrow();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// PageSchema with interfaceConfig
+// ---------------------------------------------------------------------------
+describe('PageSchema with interfaceConfig', () => {
+  it('should accept page with interfaceConfig', () => {
+    const page = PageSchema.parse({
+      name: 'customer_list_page',
+      label: '客户列表页面',
+      description: '浏览并筛选所有客户信息',
+      type: 'list',
+      object: 'customers',
+      interfaceConfig: {
+        source: 'customers',
+        levels: 1,
+        filterBy: [],
+        appearance: {
+          showDescription: true,
+          allowedVisualizations: ['grid', 'gallery', 'kanban'],
+        },
+        userFilters: {
+          elements: ['grid', 'gallery', 'kanban'],
+          tabs: [
+            { name: 'my_customers', label: 'my customers', isDefault: true, pinned: true },
+            { name: 'all_records', label: 'All records' },
+          ],
+        },
+        userActions: {
+          sort: true,
+          search: true,
+          filter: true,
+          rowHeight: true,
+          addRecordForm: false,
+        },
+        addRecord: {
+          enabled: true,
+          position: 'bottom',
+          mode: 'inline',
+        },
+        showRecordCount: true,
+        allowPrinting: true,
+      },
+      regions: [],
+    });
+
+    expect(page.interfaceConfig?.source).toBe('customers');
+    expect(page.interfaceConfig?.appearance?.allowedVisualizations).toHaveLength(3);
+    expect(page.interfaceConfig?.userActions?.sort).toBe(true);
+    expect(page.interfaceConfig?.showRecordCount).toBe(true);
+    expect(page.interfaceConfig?.allowPrinting).toBe(true);
+  });
+
+  it('should accept page without interfaceConfig (backward compatibility)', () => {
+    const page = PageSchema.parse({
+      name: 'test_page',
+      label: 'Test Page',
+      regions: [],
+    });
+    expect(page.interfaceConfig).toBeUndefined();
+  });
+
+  it('should accept dashboard page with interfaceConfig', () => {
+    const page = PageSchema.parse({
+      name: 'sales_dashboard',
+      label: 'Sales Dashboard',
+      type: 'dashboard',
+      interfaceConfig: {
+        appearance: {
+          showDescription: false,
+        },
+        allowPrinting: false,
+      },
+      regions: [],
+    });
+    expect(page.interfaceConfig?.appearance?.showDescription).toBe(false);
+    expect(page.interfaceConfig?.allowPrinting).toBe(false);
+  });
+});

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

@@ -5,6 +5,12 @@ import { SnakeCaseIdentifierSchema } from '../shared/identifiers.zod';
 import { SortItemSchema } from '../shared/enums.zod';
 import { I18nLabelSchema, AriaPropsSchema } from './i18n.zod';
 import { ResponsiveConfigSchema } from './responsive.zod';
+import {
+  UserActionsConfigSchema,
+  AppearanceConfigSchema,
+  ViewTabSchema,
+  AddRecordConfigSchema,
+} from './view.zod';
 
 /**
  * Page Region Schema
@@ -194,6 +200,43 @@ export const RecordReviewConfigSchema = z.object({
     .describe('Show review progress indicator'),
 });
 
+/**
+ * Interface Page Configuration Schema (Airtable Interface parity)
+ * Page-level declarative configuration for Airtable-style interface pages.
+ * Covers title/data binding, levels, filter by, appearance, user actions,
+ * tabs, record count, add record, and advanced options (printing).
+ *
+ * @see Airtable Interface → right panel (Page / Data / Appearance / User filters / User actions / Advanced)
+ */
+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'),
+
+  /** Appearance */
+  appearance: AppearanceConfigSchema.optional().describe('Appearance and visualization configuration'),
+
+  /** User filters */
+  userFilters: z.object({
+    elements: z.array(z.enum(['grid', 'gallery', 'kanban'])).optional()
+      .describe('Visualization element types available in user filter bar'),
+    tabs: z.array(ViewTabSchema).optional().describe('User-configurable tabs'),
+  }).optional().describe('User filter configuration'),
+
+  /** User actions */
+  userActions: UserActionsConfigSchema.optional().describe('User action toggles'),
+
+  /** Add record */
+  addRecord: AddRecordConfigSchema.optional().describe('Add record entry point configuration'),
+
+  /** Record count */
+  showRecordCount: z.boolean().optional().describe('Show record count at page bottom'),
+
+  /** Advanced */
+  allowPrinting: z.boolean().optional().describe('Allow users to print the page'),
+}).describe('Interface-level page configuration (Airtable parity)');
+
 /**
  * Page Schema
  * Defines a composition of components for a specific context.
@@ -249,6 +292,10 @@ export const PageSchema = z.object({
   isDefault: z.boolean().default(false),
   assignedProfiles: z.array(z.string()).optional(),
 
+  /** Interface Page Configuration (Airtable Interface parity) */
+  interfaceConfig: InterfacePageConfigSchema.optional()
+    .describe('Interface-level page configuration (for Airtable-style interface pages)'),
+
   /** ARIA accessibility attributes */
   aria: AriaPropsSchema.optional().describe('ARIA accessibility attributes'),
 });
@@ -262,3 +309,4 @@ export type ElementDataSource = z.infer<typeof ElementDataSourceSchema>;
 export type RecordReviewConfig = z.infer<typeof RecordReviewConfigSchema>;
 export type BlankPageLayoutItem = z.infer<typeof BlankPageLayoutItemSchema>;
 export type BlankPageLayout = z.infer<typeof BlankPageLayoutSchema>;
+export type InterfacePageConfig = z.infer<typeof InterfacePageConfigSchema>;