Integrate @objectstack/spec as foundational protocol for ObjectUI types

[Copilot]

Establishes @objectstack/spec (v0.1.1) as the universal base protocol that all ObjectUI component schemas must extend, creating a clear inheritance chain and ensuring ecosystem-wide type consistency.

Changes

New Package: @objectstack/spec (v0.1.1)

• Zero-dependency foundational protocol package
• UIComponent interface: universal base for all UI components with type discriminator, id, props, and children
• Supporting types: SchemaNode, ComponentType, ActionSchema, ComponentMetadata

Updated @object-ui/types

• BaseSchema extends UIComponent - establishes inheritance chain
• Adds ObjectUI-specific extensions: visibleOn, hiddenOn, disabledOn, className
• SchemaNode type uses BaseSchema for ObjectUI-specific type narrowing
• All 12 data-display components (AlertSchema, ChartSchema, etc.) now properly typed through this chain

Documentation & Examples

• Architecture guide explaining UIComponent → BaseSchema → Component schemas inheritance
• JSON examples for all data-display components demonstrating protocol compliance
• Property placement rules: component-specific properties at top level, HTML/ARIA attributes in props

Type Hierarchy

// @objectstack/spec - The foundational protocol
interface UIComponent {
  type: string;
  id?: string;
  props?: Record<string, any>;
  children?: SchemaNode | SchemaNode[];
}

// @object-ui/types - ObjectUI extensions
interface BaseSchema extends UIComponent {
  className?: string;
  visibleOn?: string;   // Expression-based visibility
  hiddenOn?: string;
  disabledOn?: string;
  // ... ObjectUI-specific properties
}

// Component implementations
interface ChartSchema extends BaseSchema {
  type: 'chart';
  chartType: ChartType;
  series: ChartSeries[];
  // ... chart-specific properties
}

Example Usage

{
  "type": "chart",
  "id": "sales-chart",
  "chartType": "bar",
  "series": [{ "name": "Revenue", "data": [100, 200] }],
  "visibleOn": "${user.hasAccess}",
  "className": "mb-4"
}

All changes are backward compatible - existing code continues to work without modification.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Feature]: 这里的“最高法律”是 @objectstack/spec 包 (v0.1.1)。你的所有工作（类型定义、JSON 生成、文档解释）都必须以此为基础。</issue_title>
<issue_description># Role
你是一个 ObjectUI 的核心架构师，专注于 @object-ui/types 协议层。
⚠️ CRITICAL RULE: 这里的“最高法律”是 @objectstack/spec 包 (v0.1.1)。你的所有工作（类型定义、JSON 生成、文档解释）都必须以此为基础。

Context: The Protocol

你当前正在处理 packages/types/src/data-display.ts。这个文件定义了 ObjectUI 中用于展示数据的组件规范。

继承关系 (Inheritance Chain)

1. UIComponent (@objectstack/spec): 所有 UI 组件的元定义。这是 Single Source of Truth。
2. BaseSchema (@object-ui/types/src/base.ts): ObjectUI 对 UIComponent 的扩展（添加了 visibleOn, hiddenOn 等渲染层逻辑）。
3. Specific Schema (e.g., ChartSchema): 具体的组件定义。

Data Display 组件清单

以下是本模块定义的组件类型。生成 JSON 时，必须使用正确的 type 字段：

Type	组件	核心属性 (除 BaseSchema 外)
alert	Alert	title, description, variant, icon, dismissible
statistic	Metric Card	label, value, trend ('up'/'down'), description
badge	Badge	label, variant, icon
avatar	Avatar	src, alt, fallback, size
list	List	items (ListItems[]), ordered, dividers
table	Basic Table	columns, data, caption, hoverable
data-table	Data Grid	pagination, searchable, rowActions, selectable
chart	Chart	chartType, series, categories, showLegend
timeline	Timeline	events (TimelineEvent[]), orientation
tree-view	Tree	data (TreeNode[]), multiSelect
markdown	Markdown	content (md string)
html	Raw HTML	html (string)

Constraints & Guidelines (基于 @objectstack/spec)

1. Type Consistency:

   • 在生成 JSON 时，永远不要忘记 type 字段。这是 @objectstack/spec 中的 Discriminator。
   • Example: { "type": "badge", "label": "New" } ✅

2. Expression Support:

   • 根据协议，属性值可以是静态值，也可以是表达式（如果字段支持）。
   • ObjectUI 扩展了 visibleOn / hiddenOn 来处理动态显示逻辑。

3. Strict Props mapping:

   • 如果是标准 HTML 属性或 Shadcn UI 属性，如果没有在显式接口中定义，通常放在 props 对象中（继承自 UIComponent 的特性）。
   • Example: { "type": "avatar", "props": { "role": "img" }, "src": "..." }

4. Children vs Content:

   • @objectstack/spec 定义了 children。但在此文件中，某些组件（如 Markdown）使用 content，某些（如 Alert）使用 children。生成数据时需仔细区分。

Usage Scenarios

你可以要求我：

1. Generate Protocol JSON: "根据 Spec 生成一个展示用户个人资料的卡片 JSON（包含 Avatar, Badge, List）。"
2. Verify Compliance: "检查这段 JSON 是否符合 DataTableSchema 和 UIComponent 的要求。"
3. Explain Architecture: "解释 ChartSchema 是如何从 @objectstack/spec 继承并扩展图表特有属性的。"</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [Feature]: 这里的“最高法律”是 @objectstack/spec 包 (v0.1.1)。你的所有工作（类型定义、JSON 生成、文档解释）都必须以此为基础。 #104

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[vercel]

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

Project	Deployment	Review	Updated (UTC)
objectui-docs	Error		Jan 18, 2026 4:29pm