Skip to content

Commit b67fd23

Browse files
Copilothotlong
Copilot
and
hotlong
committed
Add comprehensive UI examples in examples/ui
- Created package structure with package.json and tsconfig.json - Added detailed README.md explaining UI protocol examples - Created view.examples.ts: Grid, Kanban, Calendar, Gantt, Form views with various data sources - Created action.examples.ts: Modal, Flow, Script, URL, and Batch actions - Created dashboard.examples.ts: Sales, Service, Executive, Marketing, and Team dashboards - Created page.examples.ts: Record, Home, App, and Utility pages with component composition - Created app.examples.ts: Simple and comprehensive apps with hierarchical navigation - Created theme.examples.ts: Light, dark, colorful, and accessibility themes - All examples build successfully and demonstrate best practices Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
1 parent 8ae712b commit b67fd23

File tree

11 files changed

+4452
-0
lines changed

11 files changed

+4452
-0
lines changed

‎examples/ui/README.md‎

Lines changed: 312 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,312 @@
1+
# ObjectStack UI Protocol Examples
2+
3+
This directory contains comprehensive examples demonstrating the **UI Protocol** of ObjectStack - the presentation layer that defines how users interact with data.
4+
5+
## 📚 What's Inside
6+
7+
This example package demonstrates all major UI components of the ObjectStack Protocol:
8+
9+
### 1. **Views** (`view.examples.ts`)
10+
Different ways to display and interact with data:
11+
- **Grid View**: Traditional table/spreadsheet layout
12+
- **Kanban View**: Card-based workflow boards
13+
- **Calendar View**: Time-based event visualization
14+
- **Gantt View**: Project timeline visualization
15+
- **Custom Data Sources**: Using API providers and static data
16+
17+
### 2. **Pages** (`page.examples.ts`)
18+
Component composition patterns inspired by Salesforce Lightning Pages:
19+
- **Record Pages**: Contextual layouts for viewing/editing records
20+
- **Home Pages**: Dashboard-style landing pages
21+
- **App Pages**: Custom application screens
22+
- **Component Regions**: Flexible layout templates
23+
24+
### 3. **Dashboards** (`dashboard.examples.ts`)
25+
Analytics and metrics visualization:
26+
- **Widget Types**: Metrics, charts (bar, line, pie, donut, funnel), tables
27+
- **Filters**: Dynamic data filtering
28+
- **Layout Grid**: Responsive dashboard layouts
29+
- **Real-time Metrics**: KPIs and business intelligence
30+
31+
### 4. **Actions** (`action.examples.ts`)
32+
User interactions and workflows:
33+
- **Button Actions**: Custom buttons with various triggers
34+
- **Modal Actions**: Forms and dialogs
35+
- **Flow Actions**: Visual workflow execution
36+
- **Script Actions**: Custom JavaScript execution
37+
- **Batch Actions**: Mass operations on records
38+
39+
### 5. **Apps** (`app.examples.ts`)
40+
Complete application structure:
41+
- **Navigation Trees**: Hierarchical menus with groups
42+
- **App Branding**: Custom colors, logos, themes
43+
- **Multi-app Architecture**: Switching between business contexts
44+
- **Permission-based Access**: Role-based app visibility
45+
46+
### 6. **Themes** (`theme.examples.ts`)
47+
Visual styling and customization:
48+
- **Color Palettes**: Primary, secondary, accent colors
49+
- **Typography**: Font families and sizing
50+
- **Component Styles**: Button variants, borders, shadows
51+
- **Dark Mode**: Theme switching
52+
53+
## 🎯 Key Concepts
54+
55+
### Data-Driven UI
56+
All UI components in ObjectStack are **metadata-driven** - they are defined as JSON/TypeScript configurations rather than hardcoded implementations. This enables:
57+
58+
- **Zero-Code Customization**: Modify UIs without changing source code
59+
- **Version Control**: Track UI changes like any other code
60+
- **Dynamic Generation**: Build UIs programmatically
61+
- **Multi-tenant Isolation**: Different UIs for different customers
62+
63+
### Separation of Concerns
64+
65+
The UI Protocol is completely decoupled from:
66+
- **Data Protocol**: Business objects and logic
67+
- **System Protocol**: Runtime configuration
68+
- **Implementation**: Can be rendered by any frontend (React, Vue, Angular)
69+
70+
### Best Practices Alignment
71+
72+
ObjectStack UI Protocol draws inspiration from industry leaders:
73+
74+
| Feature | Salesforce | ServiceNow | ObjectStack |
75+
|---------|-----------|-----------|-------------|
76+
| List Views | List Views | Lists | `ListView` (grid, kanban, calendar) |
77+
| Record Pages | Lightning Pages | Forms | `Page` (regions + components) |
78+
| Dashboards | Dashboards | Performance Analytics | `Dashboard` (widgets) |
79+
| Actions | Quick Actions | UI Actions | `Action` (modal, flow, script) |
80+
| Apps | Lightning Apps | Applications | `App` (navigation + branding) |
81+
82+
## 🚀 Usage Examples
83+
84+
### Basic Grid View
85+
```typescript
86+
import { ListView } from '@objectstack/spec/ui';
87+
88+
const taskGridView: ListView = {
89+
type: 'grid',
90+
columns: ['subject', 'status', 'priority', 'due_date'],
91+
filter: [{ field: 'status', operator: '$ne', value: 'completed' }],
92+
sort: [{ field: 'due_date', order: 'asc' }],
93+
};
94+
```
95+
96+
### Kanban Board
97+
```typescript
98+
const opportunityKanban: ListView = {
99+
type: 'kanban',
100+
columns: ['name', 'amount', 'close_date'],
101+
kanban: {
102+
groupByField: 'stage',
103+
summarizeField: 'amount',
104+
columns: ['name', 'amount', 'account_name'],
105+
},
106+
};
107+
```
108+
109+
### Interactive Dashboard
110+
```typescript
111+
import { Dashboard } from '@objectstack/spec/ui';
112+
113+
const salesDashboard: Dashboard = {
114+
name: 'sales_overview',
115+
label: 'Sales Overview',
116+
widgets: [
117+
{
118+
title: 'Total Revenue',
119+
type: 'metric',
120+
object: 'opportunity',
121+
valueField: 'amount',
122+
aggregate: 'sum',
123+
layout: { x: 0, y: 0, w: 3, h: 2 },
124+
},
125+
// ... more widgets
126+
],
127+
};
128+
```
129+
130+
### Custom Action
131+
```typescript
132+
import { Action } from '@objectstack/spec/ui';
133+
134+
const convertLeadAction: Action = {
135+
name: 'convert_lead',
136+
label: 'Convert Lead',
137+
type: 'flow',
138+
target: 'lead_conversion_flow',
139+
locations: ['record_header', 'list_item'],
140+
visible: 'status = "qualified"',
141+
};
142+
```
143+
144+
## 🔗 Integration with Data Protocol
145+
146+
UI components reference objects and fields defined in the Data Protocol:
147+
148+
```typescript
149+
// Data Protocol defines the object
150+
import { ObjectSchema, Field } from '@objectstack/spec/data';
151+
152+
const Task = ObjectSchema.create({
153+
name: 'task',
154+
fields: {
155+
subject: Field.text({ required: true }),
156+
status: Field.select({ options: [...] }),
157+
priority: Field.number({ min: 1, max: 5 }),
158+
},
159+
});
160+
161+
// UI Protocol defines how to display it
162+
const taskListView: ListView = {
163+
type: 'grid',
164+
data: { provider: 'object', object: 'task' },
165+
columns: ['subject', 'status', 'priority'],
166+
};
167+
```
168+
169+
## 📖 Learning Path
170+
171+
1. **Start Simple**: Review `view.examples.ts` for basic list and form views
172+
2. **Add Interactivity**: Explore `action.examples.ts` for user interactions
173+
3. **Build Analytics**: Study `dashboard.examples.ts` for reporting
174+
4. **Compose Layouts**: Check `page.examples.ts` for advanced layouts
175+
5. **Complete Apps**: See `app.examples.ts` for full application structure
176+
177+
## 🎨 Visual Customization
178+
179+
### Theme Variables
180+
```typescript
181+
const customTheme = {
182+
colors: {
183+
primary: '#4169E1',
184+
secondary: '#9370DB',
185+
success: '#00AA00',
186+
danger: '#FF0000',
187+
},
188+
fonts: {
189+
heading: 'Inter, sans-serif',
190+
body: 'Roboto, sans-serif',
191+
},
192+
};
193+
```
194+
195+
### App Branding
196+
```typescript
197+
const salesApp = {
198+
name: 'sales_crm',
199+
branding: {
200+
primaryColor: '#4169E1',
201+
logo: '/assets/sales-logo.png',
202+
favicon: '/assets/sales-favicon.ico',
203+
},
204+
};
205+
```
206+
207+
## 🔍 Advanced Features
208+
209+
### Dynamic Data Sources
210+
```typescript
211+
// Use custom API instead of ObjectStack metadata
212+
const customListView: ListView = {
213+
type: 'grid',
214+
data: {
215+
provider: 'api',
216+
read: {
217+
url: '/api/external/data',
218+
method: 'GET',
219+
headers: { 'X-API-Key': '{api_key}' },
220+
},
221+
},
222+
columns: ['id', 'name', 'value'],
223+
};
224+
```
225+
226+
### Conditional Visibility
227+
```typescript
228+
const adminAction: Action = {
229+
name: 'delete_all',
230+
label: 'Delete All',
231+
type: 'script',
232+
visible: 'user.role = "admin" AND user.department = "engineering"',
233+
locations: ['list_toolbar'],
234+
};
235+
```
236+
237+
### Multi-level Navigation
238+
```typescript
239+
navigation: [
240+
{
241+
id: 'sales',
242+
type: 'group',
243+
label: 'Sales',
244+
children: [
245+
{ id: 'leads', type: 'object', objectName: 'lead' },
246+
{ id: 'accounts', type: 'object', objectName: 'account' },
247+
{
248+
id: 'reports',
249+
type: 'group',
250+
label: 'Reports',
251+
children: [
252+
{ id: 'sales_report', type: 'dashboard', dashboardName: 'sales_dashboard' },
253+
],
254+
},
255+
],
256+
},
257+
]
258+
```
259+
260+
## 📝 File Structure
261+
262+
```
263+
examples/ui/
264+
├── package.json # Package configuration
265+
├── tsconfig.json # TypeScript configuration
266+
├── README.md # This file
267+
└── src/
268+
├── view.examples.ts # List, Form, Kanban, Calendar views
269+
├── page.examples.ts # Record, Home, App pages
270+
├── dashboard.examples.ts # Widgets and analytics
271+
├── action.examples.ts # Buttons and interactions
272+
├── app.examples.ts # Application structure
273+
└── theme.examples.ts # Visual styling
274+
```
275+
276+
## 🤝 Related Examples
277+
278+
- **`examples/crm`**: Full CRM application using these UI patterns
279+
- **`examples/todo`**: Simple Todo app demonstrating basic UI
280+
- **`examples/modern-fields`**: Modern field types and validation
281+
282+
## 📚 References
283+
284+
- [UI Protocol Specification](../../packages/spec/src/ui/)
285+
- [Data Protocol Specification](../../packages/spec/src/data/)
286+
- [ObjectStack Architecture](../../ARCHITECTURE.md)
287+
- [Salesforce Lightning Design System](https://www.lightningdesignsystem.com/)
288+
- [ServiceNow UI Builder](https://docs.servicenow.com/bundle/washington-application-development/page/administer/ui-builder/concept/ui-builder.html)
289+
290+
## 🛠️ Building Examples
291+
292+
```bash
293+
# Install dependencies
294+
pnpm install
295+
296+
# Build this example
297+
cd examples/ui
298+
pnpm build
299+
300+
# Build all examples
301+
pnpm -r build
302+
```
303+
304+
## 💡 Contributing
305+
306+
These examples are designed to be comprehensive learning resources. When adding new examples:
307+
308+
1. **Follow naming conventions**: Use `camelCase` for configuration properties
309+
2. **Add comments**: Explain WHY, not just WHAT
310+
3. **Show variations**: Demonstrate multiple approaches
311+
4. **Keep it real**: Use realistic business scenarios
312+
5. **Reference standards**: Link to Salesforce/ServiceNow equivalents when applicable

‎examples/ui/package.json‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
{
2+
"name": "@objectstack/example-ui",
3+
"version": "1.0.0",
4+
"description": "Comprehensive UI Protocol examples demonstrating Views, Pages, Dashboards, Actions, and Themes",
5+
"private": true,
6+
"scripts": {
7+
"build": "tsc",
8+
"test": "echo \"Error: no test specified\" && exit 1"
9+
},
10+
"dependencies": {
11+
"@objectstack/spec": "workspace:*"
12+
},
13+
"devDependencies": {
14+
"typescript": "^5.0.0"
15+
}
16+
}

0 commit comments

Comments
 (0)