Skip to content

Commit cab21cc

Browse files
hotlonghotlong
committed
Update README and documentation for Object UI packages
- Added installation instructions for @object-ui/data-objectstack and @object-ui/fields. - Updated data-source documentation to reflect changes in the DataSource interface. - Introduced new Field Registry documentation to explain custom field registration and usage.
1 parent dd7663b commit cab21cc

File tree

5 files changed

+234
-3
lines changed

5 files changed

+234
-3
lines changed

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ Since this package is not yet published to NPM, here is how to play with the sou
5151
Install the core packages to use `<SchemaRenderer>` inside your Next.js or Vite app.
5252

5353
```bash
54-
npm install @object-ui/react @object-ui/components
54+
npm install @object-ui/react @object-ui/components @object-ui/data-objectstack
5555
```
5656

5757
### 🎨 **Beautiful by Default**

‎content/docs/guide/data-source.md‎

Lines changed: 24 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ Instead, the core engine communicates with your backend via a standardized `Data
88

99
## The Interface
1010

11-
All data fetching logic is abstracted into this interface defined in `@object-ui/core`:
11+
All data fetching logic is abstracted into this interface defined in `@object-ui/types`:
1212

1313
```typescript
1414
export interface DataSource {
@@ -23,9 +23,31 @@ export interface DataSource {
2323
create(resource: string, data: any): Promise<any>;
2424
update(resource: string, id: string, data: any): Promise<any>;
2525
delete(resource: string, id: string): Promise<any>;
26+
27+
/**
28+
* Get object metadata (Important for smart components)
29+
*/
30+
getObjectSchema(objectName: string): Promise<any>;
2631
}
2732
```
2833

34+
## Available Adapters
35+
36+
### ObjectStack Adapter (Official)
37+
For connecting to Steedos, Salesforce, or any ObjectStack-compatible backend.
38+
39+
```bash
40+
npm install @object-ui/data-objectstack
41+
```
42+
43+
```typescript
44+
import { createObjectStackAdapter } from '@object-ui/data-objectstack';
45+
46+
const dataSource = createObjectStackAdapter({
47+
baseUrl: 'https://api.your-instance.com'
48+
});
49+
```
50+
2951
## Usage
3052

3153
You inject the data source implementation at the root of your application via the `<SchemaRenderer>` or a provider.
@@ -53,7 +75,7 @@ function App() {
5375
If you have a proprietary backend, simply implement the interface:
5476

5577
```typescript
56-
import type { DataSource } from '@object-ui/core';
78+
import type { DataSource } from '@object-ui/types';
5779

5880
class MyCustomDataSource implements DataSource {
5981
async find(resource, params) {

‎content/docs/guide/fields.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
---
2+
title: "Field Registry"
3+
---
4+
5+
Object UI uses a **Field Registry** system to decouple the core engine from specific UI implementations of fields. This allows for rich extensibility and plugin support.
6+
7+
## Concept
8+
9+
The `@object-ui/fields` package serves as the "Universal Language" for rendering values.
10+
11+
When a component like `<ObjectGrid>` needs to render a `date` field, it doesn't import a DatePicker directly. Instead, it asks the registry:
12+
13+
> *"Hey, give me the component responsible for rendering type 'date'."*
14+
15+
This architecture allows you to:
16+
1. **Override standard fields** (e.g. replace the native date picker with a fancy one).
17+
2. **Add new field types** (e.g. add a `rating` or `signature` field).
18+
3. **Keep bundles small** (heavy components like Code Editors are loaded only if their plugin is registered).
19+
20+
## Usage
21+
22+
### 1. Registering a Custom Field
23+
24+
You can register a custom renderer globally, typically at your app's entry point.
25+
26+
```tsx
27+
// src/setup.tsx
28+
import { registerFieldRenderer, type CellRendererProps } from '@object-ui/fields';
29+
30+
const MyRatingField = ({ value, onChange }: CellRendererProps) => {
31+
return (
32+
<div className="rating">
33+
{[1, 2, 3, 4, 5].map(star => (
34+
<span
35+
key={star}
36+
onClick={() => onChange(star)}
37+
style={{ color: star <= value ? 'gold' : 'grey' }}
38+
>
39+
★
40+
</span>
41+
))}
42+
</div>
43+
);
44+
};
45+
46+
// Register it
47+
registerFieldRenderer('rating', MyRatingField);
48+
```
49+
50+
### 2. Using in Schema
51+
52+
Once registered, you can simply use the new type in your JSON schema.
53+
54+
```json
55+
{
56+
"type": "form",
57+
"fields": [
58+
{
59+
"name": "customer_satisfaction",
60+
"type": "rating",
61+
"label": "Satisfaction"
62+
}
63+
]
64+
}
65+
```
66+
67+
## Standard Fields
68+
69+
Object UI comes with built-in support for the standard [ObjectStack Protocol](/protocol) types:
70+
71+
| Type | Description |
72+
|---|---|
73+
| `text` | Single line text |
74+
| `textarea` | Multi-line text |
75+
| `number` | Numeric input |
76+
| `currency` | Currency formatting |
77+
| `percent` | Percentage values |
78+
| `date` | Date picker |
79+
| `datetime` | Date & Time picker |
80+
| `boolean` | Checkbox / Switch |
81+
| `select` | Dropdown |
82+
| `lookup` | Reference to another object |
83+
| `master_detail` | Parent-child relationship |
84+
85+
## Using Renderers in Custom Components
86+
87+
If you are building your own custom component (like a Kanban board card), you can leverage the registry to render fields without reinventing the wheel.
88+
89+
```tsx
90+
import { getCellRenderer } from '@object-ui/fields';
91+
92+
export const KanbanCard = ({ task }) => {
93+
// Get the standard renderer for a 'user' type field
94+
const UserRenderer = getCellRenderer('user');
95+
96+
return (
97+
<div className="card">
98+
<h3>{task.name}</h3>
99+
<div className="assignee">
100+
<UserRenderer
101+
value={task.assignee}
102+
field={{ type: 'user' }}
103+
/>
104+
</div>
105+
</div>
106+
);
107+
};
108+
```

‎packages/data-objectstack/README.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# @object-ui/data-objectstack
2+
3+
Official ObjectStack data adapter for Object UI.
4+
5+
## Overview
6+
7+
This package provides the `ObjectStackAdapter` class, which connects Object UI's universal `DataSource` interface with the `@objectstack/client` SDK.
8+
9+
This enables strictly typed, metadata-driven UI components to communicate seamlessly with ObjectStack backends (Steedos, Salesforce, etc.).
10+
11+
## Installation
12+
13+
```bash
14+
npm install @object-ui/data-objectstack @objectstack/client
15+
```
16+
17+
## Usage
18+
19+
```typescript
20+
import { createObjectStackAdapter } from '@object-ui/data-objectstack';
21+
import { SchemaRenderer } from '@object-ui/react';
22+
23+
// 1. Create the adapter
24+
const dataSource = createObjectStackAdapter({
25+
baseUrl: 'https://api.example.com',
26+
token: 'your-api-token' // Optional if effectively handling auth elsewhere
27+
});
28+
29+
// 2. Pass to the Renderer
30+
function App() {
31+
return (
32+
<SchemaRenderer
33+
schema={mySchema}
34+
dataSource={dataSource}
35+
/>
36+
);
37+
}
38+
```
39+
40+
## Features
41+
42+
- ✅ **CRUD Operations**: Implements `find`, `findOne`, `create`, `update`, `delete`.
43+
- ✅ **Metadata Fetching**: Implements `getObjectSchema` to power auto-generated forms and grids.
44+
- ✅ **Query Translation**: Converts Object UI's OData-like query parameters to ObjectStack's native query format.
45+
- ✅ **Bulk Operations**: Supports batch create/update/delete.

‎packages/fields/README.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# @object-ui/fields
2+
3+
The standard field library and registry for Object UI.
4+
5+
## Features
6+
7+
- 📚 **Standard Fields** - Implementation of all ObjectStack protocol fields (Text, Number, Date, Lookup, etc.)
8+
- 🔌 **Plugin System** - `FieldRegistry` allows registering custom renderers or overriding standard ones.
9+
- 🛠 **Helpers** - Utilities for schema mapping, validation, and expression evaluation.
10+
11+
## Installation
12+
13+
```bash
14+
npm install @object-ui/fields
15+
```
16+
17+
## Field Registry
18+
19+
The Field Registry is the core mechanism that allows decoupling view components from specific field implementations.
20+
21+
### Registering a Custom Field
22+
23+
You can override standard fields or add new ones:
24+
25+
```tsx
26+
import { registerFieldRenderer } from '@object-ui/fields';
27+
import { MyCustomColorPicker } from './MyCustomColorPicker';
28+
29+
// Register a new 'color' field type
30+
registerFieldRenderer('color', MyCustomColorPicker);
31+
```
32+
33+
### Using Standard Fields
34+
35+
View components use `getCellRenderer` to resolve the correct component for a field type.
36+
37+
```tsx
38+
import { getCellRenderer } from '@object-ui/fields';
39+
40+
const MyGridCell = ({ field, value }) => {
41+
const Renderer = getCellRenderer(field.type);
42+
return <Renderer field={field} value={value} />;
43+
};
44+
```
45+
46+
## Standard Field Types
47+
48+
Supported types out of the box:
49+
50+
- **Basic**: `text`, `textarea`, `number`, `boolean`
51+
- **Format**: `currency`, `percent`
52+
- **Date**: `date`, `datetime`, `time`
53+
- **Selection**: `select`, `lookup`, `master_detail`
54+
- **Contact**: `email`, `phone`, `url`
55+
- **Media**: `file`, `image`
56+
- **System**: `formula`, `summary`, `auto_number`

0 commit comments

Comments
 (0)