Skip to content

Commit 754f818

Browse files
hotlonghotlong
committed
Refactor UI framework documentation to enhance clarity and structure of standard components
1 parent ebd639c commit 754f818

File tree

1 file changed

+134
-64
lines changed

1 file changed

+134
-64
lines changed

‎docs/guide/ui-framework.md‎

Lines changed: 134 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -1,100 +1,170 @@
1-
# UI Framework Reference
1+
# Standard UI Components Reference
22

3-
The **ObjectOS UI Framework** (`@objectos/ui`) is the visual runtime for ObjectQL. It translates abstract metadata definitions into interactive React components.
3+
This document defines the standard component library for `@objectos/ui`. These components are the reference implementations for the **View & Layout Specification**.
44

5-
## 📦 Package Structure
5+
## 1. View Controller
66

7-
The package is organized into four logical layers:
7+
The entry point for rendering any object view.
88

9-
| Layer | Path | Description |
10-
| :--- | :--- | :--- |
11-
| **Smart Components** | `src/components/object-*` | Connects directly to ObjectOS Kernel/Server to fetch data and render UI. |
12-
| **Field System** | `src/components/fields/*` | Atomic inputs and display widgets for each standard data type. |
13-
| **Layout System** | `src/components/nav-*, site-header` | Application chrome, navigation, and user menus. |
14-
| **Base Primitives** | `src/components/ui/*` | Low-level atoms (Button, Input, Card) powered by Shadcn UI. |
9+
### `ObjectView`
10+
The "Switchboard" component. It connects to the Metadata Registry, fetches the requested view definition (YAML), and renders the appropriate concrete View Component.
11+
12+
- **Props**:
13+
- `objectName`: string (e.g., "tasks")
14+
- `viewName`: string (e.g., "task_kanban") - *Optional, defaults to object's default view*
15+
- `initialFilter`: FindOptions - *Optional runtime filters*
16+
- **Behavior**:
17+
1. Loads `*.view.yml`.
18+
2. Resolves `type` (e.g., `kanban`).
19+
3. Renders `<ObjectKanbanView config={...} />`.
1520

1621
---
1722

18-
## 🧩 Smart Components
23+
## 2. Standard View Components
24+
25+
These "Smart Components" implement the specific logic for each View Type defined in the spec.
1926

20-
These are "Full-Page" components that handle their own data fetching, state management, and rendering logic based on `objectName`.
27+
### `ObjectGridView`
28+
**Implements:** `type: list`, `type: grid`
2129

22-
### `ObjectGridTable`
23-
A high-performance implementation of **TanStack Table** designed for large datasets.
30+
A high-density data table based on **TanStack Table**.
2431

25-
- **Props**: `objectName` (string), `filter?` (FindOptions)
2632
- **Features**:
27-
- **Inline Editing**: Double-click cells to edit.
28-
- **Virtualization**: Handles thousands of rows smoothly.
29-
- **Auto-Columns**: Generates columns from metadata if not specified.
30-
- **Status Badges**: Automatically colors "select" fields (Green for "Active", Red for "Blocked").
33+
- **Inline Editing**: Double-click to edit (if `type: grid`).
34+
- **Columns**: Resizable, sortable, toggleable.
35+
- **Selection**: Checkbox row selection for Bulk Actions.
36+
- **Pagination**: Infinite scroll or paged navigation.
37+
- **Config Support**: `columns`, `sort`, `filters`, `row_actions`, `bulk_actions`.
3138

32-
### `ObjectForm`
33-
A dynamic form engine using **React Hook Form** + **Zod** validation.
39+
### `ObjectKanbanView`
40+
**Implements:** `type: kanban`
41+
42+
A drag-and-drop board for stage-based management.
3443

35-
- **Props**: `objectName` (string), `recordId?` (string), `mode` ('read' | 'edit')
3644
- **Features**:
37-
- **Server-Side Validation**: Displays errors returned by the Kernel.
38-
- **Conditional Logic**: Shows/hides fields based on metadata rules.
39-
- **Layout Engine**: Supports multi-column layouts defined in YAML.
45+
- **Grouping**: Buckets records by `group_by` field (Select/Lookup).
46+
- **Drag & Drop**: Updates the `group_by` field on drop.
47+
- **Summaries**: Column headers show count/sum (e.g., "Expected Revenue").
48+
- **Config Support**: `group_by`, `card`, `columns` (colors, limits).
4049

41-
### `SectionCards`
42-
A Kanban/Gallery style view for visual browsing.
50+
### `ObjectCalendarView`
51+
**Implements:** `type: calendar`
4352

44-
- **Usage**: Automatically used when `view_type: 'card'` is defined in metadata.
53+
A full-sized calendar for date-based records.
54+
55+
- **Features**:
56+
- **Views**: Month, Week, Day, Agenda.
57+
- **DnD**: Drag to reschedule (update `start_date` / `end_date`).
58+
- **Events**: Color-coded based on `color_mapping`.
59+
- **Config Support**: `start_date_field`, `end_date_field`, `color_mapping`.
60+
61+
### `ObjectTimelineView`
62+
**Implements:** `type: timeline`
63+
64+
A Gantt-chart style visualization for project planning.
65+
66+
- **Features**:
67+
- **Dependencies**: Renders connecting lines if dependency field exists.
68+
- **Resizing**: Drag edge to change duration.
69+
- **Grouping**: Group rows by User or Project.
70+
- **Config Support**: `start_date_field`, `end_date_field`, `group_by`.
71+
72+
### `ObjectGalleryView`
73+
**Implements:** `type: card`
74+
75+
A responsive grid of cards, ideal for visual assets or mobile views.
76+
77+
- **Features**:
78+
- **Cover Image**: Renders large media preview.
79+
- **Responsive**: Reflows from 1 column (mobile) to N columns (desktop).
80+
- **Config Support**: `card` (title, subtitle, image).
81+
82+
### `ObjectDetailView`
83+
**Implements:** `type: detail`
84+
85+
A read-only presentation of a single record.
86+
87+
- **Features**:
88+
- **Sections**: Layout grouping (2-col, 1-col).
89+
- **Related Lists**: Renders child records in sub-grids (e.g., "Project Tasks").
90+
- **Activity Timeline**: System generated history and comments.
91+
- **Config Support**: `sections`, `related_lists`.
92+
93+
### `ObjectFormView`
94+
**Implements:** `type: form`
95+
96+
A full-featured editor for creating or updating records.
97+
98+
- **Features**:
99+
- **Validation**: Client-side (Zod) + Server-side error mapping.
100+
- **Conditional Fields**: Hides inputs based on other field values.
101+
- **Layout**: Respects the same section layout as Detail View.
102+
- **Config Support**: `sections`, `visible_if`.
45103

46104
---
47105

48-
## 📝 Field System
106+
## 3. Structural Components
49107

50-
The `Field` component is the factory that decides which specific widget to render.
108+
Building blocks for the View layouts.
51109

52-
**Import:** `import { Field } from '@objectos/ui/components/fields/Field'`
110+
### `ViewToolbar`
111+
The header bar rendered above any view.
112+
- **Props**: `title`, `actions`, `viewSwitcherOptions`.
113+
- **Contains**:
114+
- **Breadcrumbs**: Navigation path.
115+
- **View Switcher**: Dropdown to change current view.
116+
- **Global Actions**: "New Record", "Import/Export".
53117

54-
| ObjectQL Type | UI Component | Features |
55-
| :--- | :--- | :--- |
56-
| `text`, `string` | `TextField` | Single-line text input. |
57-
| `textarea`, `longtext` | `TextAreaField` | Multi-line, auto-growing text area. |
58-
| `email` | `TextField` | Input with email validation type. Renders as `mailto:` link in read mode. |
59-
| `url` | `TextField` | Input with URL validation type. Renders as clickable link in read mode. |
60-
| `password` | `TextField` | Masked input (`type="password"`). Value is never shown in read mode. |
61-
| `tel`, `phone` | `TextField` | Telephone number input (`type="tel"`). |
62-
| `number`, `integer`, `float` | `NumberField` | Numeric input with step validation. |
63-
| `currency` | `NumberField` | Formats display with currency symbol (e.g., "$1,000.00"). |
64-
| `percent` | `NumberField` | Formats display as percentage (e.g., "50%"). |
65-
| `boolean` | `BooleanField` | Checkbox for lists, Switch toggle for forms. |
66-
| `date` | `DateField` | Popover calendar picker. |
67-
| `datetime` | `DateField` | Date picker with time selection. |
68-
| `select` | `SelectField` | Native accessible dropdown or Command palette. |
69-
| `lookup` | `LookupField` | Async search for related records. (e.g., "Select Account"). |
70-
| `master_detail` | `LookupField` | Same as lookup, but implies cascade delete and tighter coupling. |
118+
### `FilterBuilder`
119+
A complex filter construction UI.
120+
- **Features**:
121+
- Add/Remove criteria rows.
122+
- Field-aware method selection (e.g., Date fields show "Before", "After"; Text shows "Contains").
123+
- "And/Or" logic groups.
71124

72125
---
73126

74-
## 📊 Visualization Components
127+
## 📝 4. Field Components
75128

76-
ObjectOS includes standard charting capabilities for Dashboards.
129+
The `Field` component is the factory that decides which specific widget to render inside Forms, Cells, and Cards.
77130

78-
### `ChartAreaInteractive`
79-
Interactive area charts for time-series data.
131+
**Import:** `import { Field } from '@objectos/ui/components/fields/Field'`
80132

81-
- **Data Source**: Feeds directly from `kernel.aggregate()` results.
82-
- **Interactivity**: Hover tooltips, date range zooming.
133+
| ObjectQL Type | UI Component | Usage |
134+
| :--- | :--- | :--- |
135+
| `text`, `string` | `TextField` | Single-line input. |
136+
| `textarea` | `TextAreaField` | Multi-line text. |
137+
| `email`, `url`, `phone` | `TextField` | Input with specific validation/masking. |
138+
| `number`, `integer` | `NumberField` | Numeric input with step. |
139+
| `currency`, `percent` | `NumberField` | Formatted numeric display. |
140+
| `boolean` | `BooleanField` | Checkbox (Grid/List) or Switch (Form). |
141+
| `date`, `datetime` | `DateField` | Popover calendar picker. |
142+
| `select` | `SelectField` | Dropdown or Command Palette. |
143+
| `lookup`, `master_detail` | `LookupField` | Async searchable select for related records. |
144+
| `image`, `file` | `FileUploadField` | Drag-and-drop uploader + Preview. |
145+
| `formula` | `ReadOnlyField` | Display-only calculated value. |
83146

84147
---
85148

86-
## 🗄️ Layout Components
149+
## 📊 5. Visualization Components
150+
151+
Standard charting for Dashboards (`*.page.yml`).
87152

88-
Building blocks for the Application Shell (`@objectos/web`).
153+
### `ChartAreaInteractive`
154+
Interactive area chart for trends.
155+
156+
### `ChartBarInteractive`
157+
Bar chart for categorical comparisons.
89158

90-
- **`AppSidebar`**: Collapsible sidebar navigation. Renders menu items based on User Permissions.
91-
- **`SiteHeader`**: Top bar containing Search, Notifications, and User Profile.
92-
- **`NavUser`**: User profile menu with Avatar and "Sign Out" actions.
159+
### `ChartDonut`
160+
Donut/Pie chart for part-to-whole analysis.
161+
162+
---
93163

94-
## 🎨 The "Shadcn" Base
164+
## 🎨 6. Design System Primitives
95165

96-
We strictly use **Tailwind CSS** and **Radix UI** primitives (via shadcn/ui).
166+
We strictly use **Tailwind CSS** and **Radix UI** (shadcn/ui) primitives.
97167

98-
- All base components live in `src/components/ui`.
99-
- **Do not** write custom CSS. Use utility classes.
100-
- **Do not** import generic components from npm. Use the local primitives to ensure consistent theming.
168+
- **`src/components/ui/`**: Low-level atoms.
169+
- `button.tsx`, `input.tsx`, `dialog.tsx`, `popover.tsx`, `calendar.tsx`.
170+
- **Styling**: All components must use CSS variables for theming (`--primary`, `--radius`).

0 commit comments

Comments
 (0)