Skip to content

Commit e1ac1af

Browse files
hotlonghotlong
authored
Update README.md
1 parent 7e350c1 commit e1ac1af

1 file changed

Lines changed: 148 additions & 102 deletions

File tree

‎README.md‎

Lines changed: 148 additions & 102 deletions
Original file line numberDiff line numberDiff line change
@@ -2,167 +2,213 @@
22

33
<div align="center">
44

5-
**The Modular Interface Engine for the Enterprise.**
5+
**The Universal, Headless, Schema-Driven Rendering Engine.**
6+
7+
Build complex Enterprise UIs with JSON. Styled with Tailwind CSS & Shadcn UI.
68

7-
A high-performance, schema-driven UI system built on **React 18**, **Tailwind CSS**, and **Shadcn UI**.
8-
9-
[![CI](https://github.com/objectql/objectui/actions/workflows/ci.yml/badge.svg)](https://github.com/objectql/objectui/actions/workflows/ci.yml)
10-
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
11-
12-
[Documentation](https://www.objectui.org) · [Playground](https://www.objectui.org/playground) · [Report Bug](https://github.com/objectql/objectui/issues)
9+
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
10+
[![TypeScript](https://img.shields.io/badge/written%20in-TypeScript-3178C6.svg)](https://www.typescriptlang.org/)
11+
[![NPM](https://img.shields.io/npm/v/@object-ui/react.svg)](https://www.npmjs.com/package/@object-ui/react)
1312

1413
</div>
1514

1615
---
1716

1817
## 📖 Introduction
1918

20-
**Object UI** is a collection of libraries designed to transform data objects into intelligent user interfaces. It is the official presentation layer of the **ObjectQL** ecosystem, working in harmony with [ObjectQL](https://github.com/objectql/objectql) and [ObjectOS](https://github.com/objectql/objectos).
21-
22-
Unlike monolithic low-code frameworks, Object UI is built as a **modular ecosystem** under the `@object-ui` scope. You can use the core engine, the component library, or the visual designer independently or together.
23-
24-
## 📦 Ecosystem & Packages
25-
26-
Object UI is organized into several distinct packages, each serving a specific purpose:
27-
28-
| Package | NPM Name | Description |
29-
| --- | --- | --- |
30-
| **Core** | [`@object-ui/core`](./packages/core) | **The Brain.** Schema definitions, renderer registry, and logic. No UI dependencies. |
31-
| **React** | [`@object-ui/react`](./packages/react) | **The Glue.** React context, hooks, and the main `<SchemaRenderer />` component. |
32-
| **Components** | [`@object-ui/components`](./packages/components) | **The Look.** A set of high-quality UI renderers built with Tailwind CSS & Shadcn. |
33-
| **Designer** | [`@object-ui/designer`](./packages/designer) | **The Tool.** A drag-and-drop visual editor to generate Object UI schemas. |
34-
35-
## 🏗 Architecture
19+
**Object UI** is a high-performance rendering engine for React. It transforms **JSON/YAML Schemas** into modern, responsive user interfaces.
3620

37-
The architecture is designed for **maximum flexibility** and **zero bloat**.
21+
Unlike traditional low-code libraries (like Amis or RJSF) that ship with heavy, opinionated CSS, Object UI is **Tailwind-Native**. Every component is built using **Shadcn UI** primitives and utility classes, giving you complete control over the design system.
3822

39-
```mermaid
40-
graph TD
41-
A[JSON Schema] -->|Parses| B(@object-ui/core)
42-
B -->|Provides Context| C(@object-ui/react)
43-
C -->|Renders| D(@object-ui/components)
44-
D -->|Uses| E[Tailwind CSS]
45-
D -->|Uses| F[Shadcn/Radix UI]
23+
**Why Object UI?**
24+
* 🎨 **Tailwind Native:** No black-box styles. Override anything with `className`.
25+
* 🔌 **Protocol Agnostic:** Works with **ObjectQL**, any **REST API**, or just **Static JSON**.
26+
* ⚛️ **React First:** Built with React 18, Hooks, and modern Context patterns.
27+
* 📱 **Responsive:** Enterprise-grade layouts (Grid, Kanban, Dashboard) out of the box.
4628

47-
```
48-
49-
* **Decoupled Logic:** The `core` package handles schema validation and logic, meaning you could theoretically write a Vue or Svelte adapter in the future.
50-
* **Tailwind Native:** Styles are not hardcoded. Override anything using utility classes in your schema.
51-
* **Tree-Shakable:** If you only use the `Input` and `Button` components, your bundle won't include the heavy `DataGrid`.
52-
53-
## 🚀 Quick Start
29+
---
5430

55-
To use Object UI in your React project, install the core and component packages.
31+
## 📦 Installation
5632

57-
### 1. Installation
33+
Object UI is modular. Install the React core and the standard component set:
5834

5935
```bash
6036
npm install @object-ui/react @object-ui/components
6137
# or
62-
yarn add @object-ui/react @object-ui/components
38+
pnpm add @object-ui/react @object-ui/components
6339

6440
```
6541

66-
### 2. Basic Usage
42+
> **Note:** You also need `tailwindcss` and `lucide-react` installed in your project.
43+
44+
---
45+
46+
## ⚡ Quick Start
6747

68-
Define a schema and render it using the `SchemaRenderer`.
48+
### 1. Define your Schema
49+
50+
You can define your UI structure using a simple JSON object.
6951

7052
```tsx
71-
import React from 'react';
72-
import { SchemaRenderer } from '@object-ui/react';
73-
import { Form, Input, Button } from '@object-ui/components'; // Register default components
74-
75-
// 1. Register the components you want to use (or register all globally)
76-
import { registerRenderers } from '@object-ui/core';
77-
registerRenderers({
78-
'form': Form,
79-
'input': Input,
80-
'button': Button
81-
});
53+
// schema.ts
54+
import { PageSchema } from '@object-ui/types';
8255

83-
// 2. Define your Schema
84-
const schema = {
85-
type: "form",
86-
className: "space-y-4 p-6 border rounded-lg",
56+
export const myPageSchema: PageSchema = {
57+
type: 'page',
58+
title: 'User Profile',
8759
body: [
8860
{
89-
type: "input",
90-
name: "username",
91-
label: "Username",
92-
required: true
61+
type: 'grid',
62+
columns: 2,
63+
children: [
64+
{
65+
type: 'input',
66+
name: 'first_name',
67+
label: 'First Name',
68+
required: true
69+
},
70+
{
71+
type: 'input',
72+
name: 'email',
73+
label: 'Email',
74+
className: 'bg-slate-50' // Tailwind classes work here!
75+
}
76+
]
9377
},
9478
{
95-
type: "button",
96-
label: "Submit",
97-
level: "primary"
79+
type: 'button',
80+
label: 'Save Changes',
81+
level: 'primary',
82+
actionType: 'submit',
83+
className: 'mt-4'
9884
}
9985
]
10086
};
10187

102-
// 3. Render
88+
```
89+
90+
### 2. Render it!
91+
92+
Use the `<SchemaRenderer />` component to bring it to life.
93+
94+
```tsx
95+
import React from 'react';
96+
import { SchemaRenderer } from '@object-ui/react';
97+
import { standardComponents } from '@object-ui/components';
98+
import { myPageSchema } from './schema';
99+
103100
export default function App() {
104-
return <SchemaRenderer schema={schema} />;
101+
const handleAction = (action, data) => {
102+
console.log('User clicked:', action, 'Data:', data);
103+
};
104+
105+
return (
106+
<div className="p-8 max-w-4xl mx-auto">
107+
<SchemaRenderer
108+
schema={myPageSchema}
109+
components={standardComponents}
110+
onAction={handleAction}
111+
/>
112+
</div>
113+
);
105114
}
106115

107116
```
108117

109-
## 🛠 Developing
118+
---
119+
120+
## 🔌 Universal Data Source (Protocol Agnostic)
110121

111-
This project is a Monorepo managed by **TurboRepo** and **pnpm**.
122+
Object UI is not tied to any specific backend. You can use it with **any** data source.
112123

113-
### Prerequisites
124+
### Option A: Static / Uncontrolled
114125

115-
* Node.js 18+
116-
* pnpm 10+
126+
Use it as a pure controlled component for forms.
117127

118-
### Setup
128+
```tsx
129+
<SchemaRenderer
130+
schema={formSchema}
131+
value={formData}
132+
onChange={setFormData}
133+
/>
119134

120-
```bash
121-
# 1. Clone the repository
122-
git clone https://github.com/objectql/objectui.git
135+
```
123136

124-
# 2. Install dependencies
125-
pnpm install
137+
### Option B: Generic REST API
126138

127-
# 3. Start the development playground
128-
pnpm dev
139+
Connect to any API using a `DataSource` adapter.
129140

130-
```
141+
```tsx
142+
import { RestDataSource } from '@object-ui/data-rest';
143+
144+
const api = new RestDataSource({
145+
baseUrl: '[https://api.example.com/v1](https://api.example.com/v1)',
146+
headers: { Authorization: 'Bearer ...' }
147+
});
131148

132-
### Testing
149+
<SchemaRenderer
150+
schema={pageSchema}
151+
dataSource={api} // The components will fetch data automatically
152+
/>
133153

134-
We use **Vitest** for testing. All tests are located in `__tests__` directories within each package.
154+
```
135155

136-
```bash
137-
# Run all tests
138-
pnpm test
156+
### Option C: ObjectQL (The Perfect Match)
139157

140-
# Run tests in watch mode
141-
pnpm test:watch
158+
If you use **ObjectQL**, Object UI provides zero-config integration.
142159

143-
# Run tests with UI
144-
pnpm test:ui
160+
```tsx
161+
import { ObjectQLDataSource } from '@object-ui/data-objectql';
145162

146-
# Generate coverage report
147-
pnpm test:coverage
163+
<SchemaRenderer
164+
schema={pageSchema}
165+
dataSource={new ObjectQLDataSource()}
166+
/>
148167

149168
```
150169

151-
### Building
170+
---
152171

153-
```bash
154-
# Build all packages
155-
pnpm build
172+
## 🧩 Architecture
156173

157-
# Lint all packages
158-
pnpm lint
174+
This project is organized as a Monorepo:
159175

160-
```
176+
| Package | Description |
177+
| --- | --- |
178+
| **`@object-ui/types`** | The protocol definitions. Pure TypeScript interfaces. |
179+
| **`@object-ui/core`** | The logic engine. Data scoping, validation, evaluation. |
180+
| **`@object-ui/react`** | The React framework adapter. |
181+
| **`@object-ui/components`** | The standard UI library implementation (Shadcn + Tailwind). |
182+
| **`@object-ui/plugin-*`** | Lazy-loaded complex components (e.g., AG Grid, Monaco). |
161183

162-
## 🤝 Contributing
184+
---
185+
186+
## 🤝 Comparison
163187

164-
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
188+
| Feature | Object UI | Amis / Lowcode Engine | Formily / RJSF |
189+
| --- | --- | --- | --- |
190+
| **Styling** | **Tailwind Native** (Utility) | Opinionated CSS (Hard to override) | Various (AntD/MUI wrappers) |
191+
| **Scope** | **Full Pages** & Apps | Full Pages & Apps | Mostly Forms |
192+
| **Protocol** | **JSON Schema** | Custom JSON | JSON Schema / Internal |
193+
| **Dependencies** | Light (Radix UI) | Heavy (Bootstrap/JQuery legacy) | Medium |
194+
| **Backend** | **Agnostic** | Tightly coupled (Amis) | Agnostic |
195+
196+
---
197+
198+
## 🛤️ Roadmap
199+
200+
* [ ] **Visual Designer:** Drag-and-drop schema builder.
201+
* [ ] **Plugin Ecosystem:** Support for AG Grid Enterprise, ECharts, and Monaco Editor.
202+
* [ ] **SSR Support:** Full compatibility with Next.js App Router.
165203

166204
## 📄 License
167205

168-
This project is licensed under the MIT License.
206+
Licensed under the [MIT License](https://www.google.com/search?q=LICENSE).
207+
208+
---
209+
210+
<div align="center">
211+
<sub>Built with ❤️ by the Object Ecosystem Team.</sub>
212+
</div>
213+
214+
```

0 commit comments

Comments
 (0)