feat(ui): Interface Foundation — Phase A (v3.2)

[Copilot]

Implements Phase A of the Airtable Interface parity roadmap, introducing a self-contained, shareable, multi-page application surface distinct from the existing AppSchema navigation container. The Interface concept enables role-specific surfaces that stitch together views, elements, and actions into cohesive experiences.

New: InterfaceSchema (src/ui/interface.zod.ts)

• InterfaceSchema — top-level entity with pages, branding, role assignments, default landing page
• InterfaceBrandingSchema — extends AppBrandingSchema with coverImage
• defineInterface() factory — exported from root index.ts alongside defineView, defineApp, defineFlow, defineAgent

Unified Page System (page.zod.ts)

• PageTypeSchema — unified 16-type enum: 4 platform (record, home, app, utility) + 12 interface (dashboard, grid, list, gallery, kanban, calendar, timeline, form, record_detail, record_review, overview, blank)
• RecordReviewConfigSchema — sequential record review/approval with actions (approve/reject/skip/custom), navigation modes, field updates, progress indicator
• icon property added to PageSchema for interface navigation
• InterfaceSchema.pages references PageSchema directly (no separate InterfacePageSchema)

Content Elements (page.zod.ts, component.zod.ts)

• Added element:text, element:number, element:image, element:divider to PageComponentType
• ElementTextPropsSchema — markdown content, variant, alignment
• ElementNumberPropsSchema — object/field aggregation (count/sum/avg/min/max), format, prefix/suffix
• ElementImagePropsSchema — src, alt, object-fit, height
• All registered in ComponentPropsMap

Per-element Data Binding (page.zod.ts)

• ElementDataSourceSchema — object, view, filter, sort, limit
• dataSource optional property on PageComponentSchema — overrides page-level object context for multi-object dashboards

Shared Primitives (shared/enums.zod.ts)

• Extracted SortItemSchema ({ field, order }) reusing SortDirectionEnum — replaces inline sort definitions across UI schemas

Documentation & Roadmap

• ROADMAP.md Phase 8.1 Phase A marked as ✅ complete
• Codebase metrics updated (177 schema files, 199 test files, 5468 tests)
• Phase 1 deliverables updated with Interface, Content Elements, defineInterface()
• Design doc (airtable-interface-gap-analysis.md) status updated to "Phase A Implemented"
• Design doc Phase A checklist marked complete with additional merge/extract items
• Decision log expanded with entries Migrate from npm to pnpm #6-8 (PageSchema merge, SortItemSchema extraction, branding extend)

const portal = defineInterface({
  name: 'order_management',
  label: 'Order Management',
  object: 'order',
  pages: [
    {
      name: 'page_dashboard', label: 'Dashboard', type: 'dashboard',
      regions: [{
        name: 'main',
        components: [
          { type: 'element:number', properties: { object: 'order', aggregate: 'sum', field: 'total', format: 'currency' },
            dataSource: { object: 'order', filter: { status: 'completed' } } },
        ],
      }],
    },
    {
      name: 'page_review', label: 'Review', type: 'record_review',
      recordReview: {
        object: 'order',
        actions: [
          { label: 'Approve', type: 'approve', field: 'status', value: 'approved' },
          { label: 'Reject', type: 'reject', field: 'status', value: 'rejected' },
        ],
      },
      regions: [],
    },
  ],
});

61 new tests. All 199 test files (5468 tests) pass.

Original prompt

按 roadmap 完成 ui协议

8.1 UI Protocol Enhancement — Airtable Interface Parity

See Airtable Interface Gap Analysis for the full evaluation.
Phase A: Interface Foundation (v3.2)

InterfaceSchema — Self-contained, shareable, multi-page application surface (src/ui/interface.zod.ts)
RecordReviewConfigSchema — Sequential record review/approval page type with navigation and actions
Content elements — element:text, element:number, element:image, element:divider as PageComponentType extensions
Per-element data binding — dataSource property on PageComponentInstanceSchema for multi-object pages
Element props — ElementTextPropsSchema, ElementNumberPropsSchema, ElementImagePropsSchema

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
objectstack-play	Ready	Preview, Comment	Feb 16, 2026 6:49am
spec	Ready	Preview, Comment	Feb 16, 2026 6:49am

[hotlong]

@copilot 评估这个设计方案和现有ui元数据是否有功能重叠，并提出改进方案。

[Copilot]

@copilot 评估这个设计方案和现有ui元数据是否有功能重叠，并提出改进方案。

完成了完整的功能重叠评估并已实施改进（a0a3d1a）。

重叠分析

存在重叠但设计上合理的领域：

领域	InterfaceSchema (新)	现有 Schema	结论
页面组合	InterfacePageSchema 复用 PageRegionSchema/PageVariableSchema	PageSchema	✅ 通过 import 复用，非重复定义
视图类型	InterfacePageTypeSchema (dashboard/grid/kanban 等 12 种)	ListViewSchema.type (grid/kanban 等 7 种)	✅ 不同抽象层级 — 页面类型 vs 数据视图类型
组件系统	新 content elements 在 PageComponentType 中扩展	现有 structure/record/AI 组件	✅ 统一在同一枚举中，复用 ComponentPropsMap

已修复的实际重叠：

1. 排序模式重复 — { field, order } 在 ElementDataSourceSchema、RecordReviewConfigSchema、ListViewSchema、RecordRelatedListProps 中各自内联定义 → 已提取共享 SortItemSchema 到 shared/enums.zod.ts
2. 品牌配置重复 — InterfaceBrandingSchema 与 AppBrandingSchema 有 2/3 字段完全一致（primaryColor、logo）→ 已改为 AppBrandingSchema.extend() 仅新增 coverImage
3. 聚合函数重复 — ElementNumberPropsSchema 中 count|sum|avg|min|max 与 DashboardWidgetSchema 完全一致，shared/enums.zod.ts 中已有 AggregationFunctionEnum 但 UI 层未引用（UI 层使用基础 5 种为有意子集，完整枚举含 stddev/variance 等，标记为未来统一项）

架构清晰度：

App (导航容器)
  └── Interface (可共享的角色专属表面) ← 新增
       └── InterfacePage (12种页面类型)
            └── Region → PageComponent (含 dataSource 绑定)
                 └── ComponentPropsMap (含 element:* 新类型)

View (数据驱动视图) — 独立于 Interface，可在 Interface 页面内嵌入
Dashboard (仪表盘) — 独立实体，与 InterfacePage type=dashboard 互补

Security: CodeQL 无告警。

[hotlong]

@copilot 评估 InterfacePageSchema 是否应该合并到 PageSchema

[Copilot]

Pull request overview

This PR implements Phase A of the Airtable Interface parity roadmap, introducing a self-contained, shareable, multi-page application surface distinct from the existing AppSchema navigation container. The Interface concept enables role-specific surfaces that stitch together views, elements, and actions into cohesive experiences.

Changes:

• Introduces InterfaceSchema with 12 page types (dashboard, grid, list, gallery, kanban, calendar, timeline, form, record_detail, record_review, overview, blank)
• Adds RecordReviewConfigSchema for sequential record review/approval workflows with configurable actions and navigation modes
• Extracts shared SortItemSchema to shared/enums.zod.ts for reuse across UI schemas
• Implements per-element data binding via ElementDataSourceSchema enabling multi-object pages where each element can query different data sources
• Adds four content element types (element:text, element:number, element:image, element:divider) with corresponding prop schemas

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
packages/spec/src/ui/interface.zod.ts	New file defining InterfaceSchema, InterfacePageSchema, RecordReviewConfigSchema, and InterfaceBrandingSchema with comprehensive documentation and examples
packages/spec/src/ui/interface.test.ts	Comprehensive test suite with 57 tests covering all schemas, validation rules, edge cases, and end-to-end scenarios
packages/spec/src/ui/page.zod.ts	Adds ElementDataSourceSchema for per-element data binding and extends PageComponentType enum with four content element types
packages/spec/src/ui/component.zod.ts	Adds ElementTextPropsSchema, ElementNumberPropsSchema, and ElementImagePropsSchema with corresponding ComponentPropsMap entries
packages/spec/src/ui/index.ts	Exports the new interface.zod.ts module
packages/spec/src/shared/enums.zod.ts	Extracts reusable SortItemSchema pattern (field + order) from inline definitions
packages/spec/src/shared/enums.test.ts	Adds comprehensive tests for SortItemSchema validation

[Copilot]

The defineInterface factory function follows the same pattern as defineView, defineApp, defineFlow, and defineAgent, which are all exported from the root index.ts for developer convenience. However, defineInterface is not exported there. For consistency with the established pattern, consider adding:

export { defineInterface } from './ui/interface.zod';

to packages/spec/src/index.ts around line 80, near the other DX Helper Functions.

[Copilot]

Added in 0e35543 — defineInterface is now exported from root index.ts alongside defineView, defineApp, defineFlow, and defineAgent.

[Copilot]

@copilot 评估 InterfacePageSchema 是否应该合并到 PageSchema

已完成合并（11b0157, 420c896）。

合并前的对比：

属性	InterfacePageSchema	PageSchema	重叠度
label, description	✓	✓	100%
type (枚举)	12 种	4 种	不同值但相同概念
variables	导入 PageVariableSchema	PageVariableSchema	100%
object	✓	✓	100%
template	✓	✓	100%
regions	导入 PageRegionSchema	PageRegionSchema	100%
aria	✓	✓	100%
唯一差异	id, icon, recordReview	name, isDefault, assignedProfiles

9 个属性中 7 个完全一致，应该合并。

合并结果：

• PageTypeSchema 统一为 16 种类型（4 平台 + 12 接口）
• RecordReviewConfigSchema 和 icon 合入 PageSchema
• InterfaceSchema.pages 直接引用 PageSchema
• 删除 InterfacePageSchema、InterfacePageTypeSchema
• homePageId → homePageName（与 PageSchema.name 一致）

PageSchema (统一)
  ├── type: 'record' | 'home' | 'app' | 'utility'       ← 平台页面
  ├── type: 'dashboard' | 'grid' | 'kanban' | ...        ← 接口页面
  ├── icon, recordReview                                   ← 从 InterfacePageSchema 合入
  └── regions, variables, template, object, aria           ← 共享

InterfaceSchema
  └── pages: PageSchema[]                                  ← 直接引用

199 文件，5468 测试全部通过。

[hotlong]

更新文档和roadmap

[hotlong]

更新文档和roadmap

@copilot

[Copilot]

更新文档和roadmap

@copilot

已完成（0e35543）。

ROADMAP.md 更新：

• Phase 8.1 Phase A 所有项标记为 ✅ 完成
• 代码指标更新：177 schema 文件、199 测试文件、5468 测试
• Phase 1 交付物新增 Interface、Content Elements、defineInterface()

设计文档更新：

• 状态从 "Proposal" 更新为 "Phase A Implemented"
• Phase A 清单全部标记完成，新增合并和共享 schema 提取项
• 决策日志新增 Migrate from npm to pnpm #6-8：PageSchema 合并、SortItemSchema 提取、InterfaceBrandingSchema extend

额外：

• defineInterface 已导出到 root index.ts（审查建议）