Skip to content

Commit 226b200

Browse files
Copilothotlong
Copilot
and
hotlong
committed
Add comprehensive documentation for ObjectStack spec integration
Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
1 parent ce91886 commit 226b200

1 file changed

Lines changed: 222 additions & 0 deletions

File tree

‎docs/architecture/objectstack-spec-integration.md‎

Lines changed: 222 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,222 @@
1+
# Architecture: ObjectStack Spec Integration
2+
3+
## Overview
4+
5+
This document explains how ObjectUI integrates with `@objectstack/spec` (v0.1.1) as the foundational protocol for all UI components.
6+
7+
## The Inheritance Chain
8+
9+
```
10+
@objectstack/spec (v0.1.1) ← The "Highest Law" - Universal Protocol
11+
↓
12+
UIComponent ← Base interface for all UI components
13+
↓
14+
BaseSchema (@object-ui/types) ← ObjectUI-specific extensions
15+
↓
16+
Specific Schemas ← Component implementations
17+
↓
18+
Component Renderers ← UI implementations
19+
```
20+
21+
### 1. UIComponent (@objectstack/spec)
22+
23+
The foundational interface that defines the core protocol for schema-driven UI:
24+
25+
```typescript
26+
interface UIComponent {
27+
type: string; // Component type discriminator
28+
id?: string; // Unique identifier
29+
props?: Record<string, any>; // Component-specific properties
30+
children?: SchemaNode | SchemaNode[]; // Child content
31+
[key: string]: any; // Extensibility
32+
}
33+
```
34+
35+
**Why this is the "highest law":**
36+
- Defines the universal contract for all UI components
37+
- Ensures interoperability across the ObjectStack ecosystem
38+
- Provides the type discriminator pattern
39+
- Enables JSON serialization
40+
41+
### 2. BaseSchema (@object-ui/types)
42+
43+
Extends `UIComponent` with ObjectUI-specific rendering logic:
44+
45+
```typescript
46+
interface BaseSchema extends UIComponent {
47+
// Inherited from UIComponent
48+
type: string;
49+
id?: string;
50+
children?: SchemaNode | SchemaNode[];
51+
52+
// ObjectUI extensions
53+
className?: string; // Tailwind CSS classes
54+
visible?: boolean; // Static visibility
55+
visibleOn?: string; // Dynamic visibility (expression)
56+
hidden?: boolean; // Static hiding
57+
hiddenOn?: string; // Dynamic hiding (expression)
58+
disabled?: boolean; // Static disabled state
59+
disabledOn?: string; // Dynamic disabled state (expression)
60+
61+
// Additional ObjectUI properties
62+
name?: string;
63+
label?: string;
64+
description?: string;
65+
placeholder?: string;
66+
style?: Record<string, string | number>;
67+
data?: any;
68+
body?: SchemaNode | SchemaNode[];
69+
testId?: string;
70+
ariaLabel?: string;
71+
}
72+
```
73+
74+
### 3. Specific Schemas (e.g., ChartSchema)
75+
76+
Component-specific interfaces that extend `BaseSchema`:
77+
78+
```typescript
79+
interface ChartSchema extends BaseSchema {
80+
type: 'chart'; // Type discriminator
81+
chartType: ChartType; // Chart-specific property
82+
title?: string;
83+
description?: string;
84+
categories?: string[];
85+
series: ChartSeries[];
86+
height?: string | number;
87+
showLegend?: boolean;
88+
showGrid?: boolean;
89+
animate?: boolean;
90+
config?: Record<string, any>;
91+
}
92+
```
93+
94+
## Data Display Components
95+
96+
The following components are defined in `@object-ui/types/data-display`:
97+
98+
| Type | Component | Schema Interface | Key Properties |
99+
|------|-----------|-----------------|----------------|
100+
| `alert` | Alert | `AlertSchema` | title, description, variant, icon, dismissible |
101+
| `statistic` | Metric Card | `StatisticSchema` | label, value, trend, description, icon |
102+
| `badge` | Badge | `BadgeSchema` | label, variant, icon |
103+
| `avatar` | Avatar | `AvatarSchema` | src, alt, fallback, size, shape |
104+
| `list` | List | `ListSchema` | items, ordered, dividers |
105+
| `table` | Basic Table | `TableSchema` | columns, data, caption, hoverable |
106+
| `data-table` | Data Grid | `DataTableSchema` | pagination, searchable, rowActions, selectable |
107+
| `chart` | Chart | `ChartSchema` | chartType, series, categories, showLegend |
108+
| `timeline` | Timeline | `TimelineSchema` | events, orientation, position |
109+
| `tree-view` | Tree View | `TreeViewSchema` | data, multiSelect, showLines |
110+
| `markdown` | Markdown | `MarkdownSchema` | content, sanitize |
111+
| `html` | Raw HTML | `HtmlSchema` | html |
112+
113+
## Usage Examples
114+
115+
### 1. Simple Component (Compliant with UIComponent)
116+
117+
```json
118+
{
119+
"type": "badge",
120+
"id": "status-badge",
121+
"props": {
122+
"label": "New",
123+
"variant": "default"
124+
}
125+
}
126+
```
127+
128+
### 2. Component with ObjectUI Extensions
129+
130+
```json
131+
{
132+
"type": "alert",
133+
"id": "welcome-alert",
134+
"title": "Welcome!",
135+
"description": "Thank you for using ObjectUI",
136+
"variant": "default",
137+
"icon": "info",
138+
"dismissible": true,
139+
"visibleOn": "${user.isNewUser}",
140+
"className": "mb-4"
141+
}
142+
```
143+
144+
### 3. Complex Component with Children
145+
146+
```json
147+
{
148+
"type": "flex",
149+
"id": "user-profile",
150+
"props": {
151+
"direction": "col",
152+
"gap": 4
153+
},
154+
"children": [
155+
{
156+
"type": "avatar",
157+
"src": "https://github.com/shadcn.png",
158+
"fallback": "JD",
159+
"size": "lg"
160+
},
161+
{
162+
"type": "statistic",
163+
"label": "Followers",
164+
"value": "1,234",
165+
"trend": "up"
166+
},
167+
{
168+
"type": "badge",
169+
"label": "Pro Member",
170+
"variant": "default"
171+
}
172+
]
173+
}
174+
```
175+
176+
### 4. Data Display with Chart
177+
178+
```json
179+
{
180+
"type": "chart",
181+
"id": "sales-chart",
182+
"chartType": "bar",
183+
"title": "Monthly Sales",
184+
"categories": ["Jan", "Feb", "Mar", "Apr", "May", "Jun"],
185+
"series": [
186+
{
187+
"name": "Revenue",
188+
"data": [12000, 15000, 18000, 14000, 22000, 25000],
189+
"color": "#3b82f6"
190+
}
191+
],
192+
"showLegend": true,
193+
"height": 400
194+
}
195+
```
196+
197+
## Protocol Compliance Rules
198+
199+
When creating or using components:
200+
201+
1. ✅ **MUST** extend from `UIComponent` (directly or indirectly via `BaseSchema`)
202+
2. ✅ **MUST** include a `type` field (the discriminator)
203+
3. ✅ **MUST** use the correct type value from the component registry
204+
4. ✅ **SHOULD** place component-specific properties at the top level (not in props)
205+
5. ✅ **SHOULD** use `props` for standard HTML attributes (role, aria-*, data-*)
206+
6. ✅ **SHOULD** support `children` for composable components
207+
7. ✅ **SHOULD** support `id` for unique identification
208+
8. ✅ **MAY** use ObjectUI extensions (className, visibleOn, etc.)
209+
210+
## Related Packages
211+
212+
- **[@objectstack/spec](../../packages/objectstack-spec)** - Universal UI component specification
213+
- **[@object-ui/types](../../packages/types)** - ObjectUI protocol extensions
214+
- **[@object-ui/core](../../packages/core)** - Schema validation and expression engine
215+
- **[@object-ui/react](../../packages/react)** - React renderer
216+
- **[@object-ui/components](../../packages/components)** - Shadcn/Tailwind implementation
217+
218+
## References
219+
220+
- [ObjectStack Spec README](../../packages/objectstack-spec/README.md)
221+
- [Object UI Types README](../../packages/types/README.md)
222+
- [Data Display Examples](../../packages/types/examples/data-display-examples.json)

0 commit comments

Comments
 (0)