diff --git a/content/docs/03-objectui/actions/api-request.mdx b/content/docs/03-objectui/actions/api-request.mdx new file mode 100644 index 0000000..ed2d496 --- /dev/null +++ b/content/docs/03-objectui/actions/api-request.mdx @@ -0,0 +1,136 @@ +--- +title: API Request +description: Make HTTP requests +--- + +# API Request + +Make HTTP requests to backend endpoints. + +## Protocol + +```typescript +{ + type: 'api', + api: string, // API endpoint + method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE', + data?: object | string, // Request body (template supported) + headers?: object, // Request headers + confirm?: string, // Confirmation message + onSuccess?: Action, // Success handler + onError?: Action, // Error handler +} +``` + +## Examples + +### Basic Request + +```json +{ + "type": "button", + "label": "Save", + "onClick": { + "type": "api", + "api": "/api/users/${userId}", + "method": "PUT", + "data": "${formData}", + "confirm": "Save changes?", + "onSuccess": { + "type": "toast", + "message": "Saved successfully!" + } + } +} +``` + +### DELETE with Confirmation + +```json +{ + "type": "api", + "api": "/api/users/${id}", + "method": "DELETE", + "confirm": "Are you sure you want to delete this user?", + "onSuccess": [ + { "type": "toast", "message": "User deleted" }, + { "type": "reload" } + ], + "onError": { + "type": "toast", + "message": "Failed to delete user", + "variant": "error" + } +} +``` + +### POST with Custom Headers + +```json +{ + "type": "api", + "api": "/api/upload", + "method": "POST", + "headers": { + "Content-Type": "multipart/form-data" + }, + "data": "${fileData}" +} +``` + +## HTTP Methods + +- **GET** - Retrieve data +- **POST** - Create new resources +- **PUT** - Update entire resources +- **PATCH** - Partial updates +- **DELETE** - Remove resources + +## Template Variables + +Use template syntax in `api`, `data`, and other string fields: + +```json +{ + "api": "/api/users/${userId}/posts/${postId}", + "data": { + "title": "${formData.title}", + "content": "${formData.content}" + } +} +``` + +## Action Chaining + +Chain multiple actions on success or error: + +```json +{ + "type": "api", + "api": "/api/submit", + "method": "POST", + "onSuccess": [ + { "type": "toast", "message": "Success!" }, + { "type": "navigate", "url": "/dashboard" } + ] +} +``` + +## Confirmation Dialogs + +Add a confirmation prompt before executing: + +```json +{ + "type": "api", + "api": "/api/delete-all", + "method": "POST", + "confirm": "This will delete all data. Are you sure?" +} +``` + +## Related + +- **[Form](/docs/03-objectui/container-components/form)** - Form submission +- **[Toast](/docs/03-objectui/actions/toast)** - User feedback +- **[Navigate](/docs/03-objectui/actions/navigate)** - Redirect after API calls diff --git a/content/docs/03-objectui/actions/dialog.mdx b/content/docs/03-objectui/actions/dialog.mdx new file mode 100644 index 0000000..ff06692 --- /dev/null +++ b/content/docs/03-objectui/actions/dialog.mdx @@ -0,0 +1,122 @@ +--- +title: Dialog +description: Open modal dialogs +--- + +# Dialog + +Open a modal dialog with custom content. + +## Protocol + +```typescript +{ + type: 'dialog', + title?: string, + width?: number | string, + body: Component, + footer?: Component[], + closable?: boolean, +} +``` + +## Examples + +### Form Dialog + +```json +{ + "type": "button", + "label": "Add User", + "onClick": { + "type": "dialog", + "title": "Create New User", + "width": 600, + "body": { + "type": "form", + "api": "/api/users", + "fields": [ + { "type": "input", "name": "name", "label": "Name", "required": true }, + { "type": "input", "name": "email", "label": "Email", "inputType": "email", "required": true } + ] + } + } +} +``` + +### Confirmation Dialog + +```json +{ + "type": "dialog", + "title": "Confirm Action", + "body": { + "type": "text", + "value": "Are you sure you want to proceed?" + }, + "footer": [ + { "type": "button", "label": "Cancel", "onClick": { "type": "close" } }, + { "type": "button", "label": "Confirm", "onClick": { "type": "api", "api": "/api/confirm" } } + ] +} +``` + +### Content Dialog + +```json +{ + "type": "button", + "label": "View Details", + "onClick": { + "type": "dialog", + "title": "User Details", + "width": "80%", + "body": { + "type": "card", + "body": [ + { "type": "text", "value": "Name: ${user.name}" }, + { "type": "text", "value": "Email: ${user.email}" }, + { "type": "text", "value": "Role: ${user.role}" } + ] + } + } +} +``` + +## Features + +### Width + +Control dialog width with: +- Fixed pixel values: `600` +- Percentage: `"80%"` +- Preset sizes: `"sm"`, `"md"`, `"lg"`, `"xl"` + +### Closable + +Set `closable: false` to prevent users from closing the dialog via the close button or ESC key. + +### Body Content + +The dialog body can contain any component: +- Forms for data entry +- Cards for content display +- Tables for data selection +- Custom component compositions + +### Footer + +Add custom footer buttons for actions like Cancel, Confirm, Save, etc. + +## Use Cases + +- Create/edit forms +- Confirmation prompts +- Detail views +- Multi-step wizards +- Image galleries + +## Related + +- **[Form](/docs/03-objectui/container-components/form)** - Forms in dialogs +- **[API Request](/docs/03-objectui/actions/api-request)** - Submit from dialog diff --git a/content/docs/03-objectui/actions/index.mdx b/content/docs/03-objectui/actions/index.mdx new file mode 100644 index 0000000..7581acb --- /dev/null +++ b/content/docs/03-objectui/actions/index.mdx @@ -0,0 +1,103 @@ +--- +title: Actions +description: Interactive behaviors and event handlers in ObjectUI +--- + +# Actions + +Actions define interactive behaviors in ObjectUI. + +## Action Types + +- **[API Request](/docs/03-objectui/actions/api-request)** - Make HTTP requests +- **[Navigate](/docs/03-objectui/actions/navigate)** - Navigate to different pages +- **[Dialog](/docs/03-objectui/actions/dialog)** - Open modal dialogs +- **[Toast](/docs/03-objectui/actions/toast)** - Show notification messages + +## Overview + +Actions are the interactive layer of ObjectUI, handling user events and triggering responses. They support: + +- **Chaining**: Actions can trigger other actions (onSuccess, onError) +- **Template Substitution**: Use `${variable}` syntax for dynamic values +- **Confirmation**: Add confirm prompts before execution +- **Error Handling**: Built-in error handling and user feedback + +## Common Patterns + +### Form Submission + +```json +{ + "type": "form", + "fields": [...], + "onSubmit": { + "type": "api", + "api": "/api/users", + "method": "POST", + "onSuccess": { + "type": "toast", + "message": "User created successfully!" + } + } +} +``` + +### Button Actions + +```json +{ + "type": "button", + "label": "Save", + "onClick": { + "type": "api", + "api": "/api/save", + "method": "POST", + "data": "${formData}" + } +} +``` + +### Navigation + +```json +{ + "type": "button", + "label": "View Details", + "onClick": { + "type": "navigate", + "url": "/users/${userId}" + } +} +``` + +## Action Chaining + +Actions can trigger other actions on success or error: + +```json +{ + "type": "api", + "api": "/api/users/${id}", + "method": "DELETE", + "confirm": "Delete this user?", + "onSuccess": [ + { "type": "toast", "message": "User deleted" }, + { "type": "reload" } + ], + "onError": { + "type": "toast", + "message": "Failed to delete user", + "variant": "error" + } +} +``` + +## Next Steps + +Explore individual action types for detailed protocol definitions and examples: + +- **[API Request](/docs/03-objectui/actions/api-request)** - HTTP requests +- **[Navigate](/docs/03-objectui/actions/navigate)** - Page navigation +- **[Dialog](/docs/03-objectui/actions/dialog)** - Modal dialogs +- **[Toast](/docs/03-objectui/actions/toast)** - Notifications diff --git a/content/docs/03-objectui/actions/meta.json b/content/docs/03-objectui/actions/meta.json new file mode 100644 index 0000000..5305a5f --- /dev/null +++ b/content/docs/03-objectui/actions/meta.json @@ -0,0 +1,10 @@ +{ + "title": "Actions", + "pages": [ + "index", + "api-request", + "navigate", + "dialog", + "toast" + ] +} diff --git a/content/docs/03-objectui/actions/navigate.mdx b/content/docs/03-objectui/actions/navigate.mdx new file mode 100644 index 0000000..a413a69 --- /dev/null +++ b/content/docs/03-objectui/actions/navigate.mdx @@ -0,0 +1,105 @@ +--- +title: Navigate +description: Navigate to different pages +--- + +# Navigate + +Navigate to a different page or URL. + +## Protocol + +```typescript +{ + type: 'navigate', + url: string, // Target URL (template supported) + newTab?: boolean, // Open in new tab + replace?: boolean, // Replace current history entry +} +``` + +## Examples + +### Basic Navigation + +```json +{ + "type": "button", + "label": "View Details", + "onClick": { + "type": "navigate", + "url": "/users/${userId}" + } +} +``` + +### Open in New Tab + +```json +{ + "type": "button", + "label": "External Link", + "onClick": { + "type": "navigate", + "url": "https://example.com", + "newTab": true + } +} +``` + +### Replace History + +```json +{ + "type": "navigate", + "url": "/login", + "replace": true +} +``` + +### Navigate After API Call + +```json +{ + "type": "api", + "api": "/api/users", + "method": "POST", + "data": "${formData}", + "onSuccess": { + "type": "navigate", + "url": "/users/${response.id}" + } +} +``` + +## Features + +### Template URLs + +Use template variables in the URL: + +```json +{ + "url": "/users/${userId}/posts/${postId}" +} +``` + +### New Tab + +Open links in a new browser tab with `newTab: true`. + +### History Management + +Use `replace: true` to replace the current history entry instead of adding a new one. Useful for login redirects. + +## Use Cases + +- Navigate to detail pages +- Redirect after form submission +- Open external links +- Navigate back/forward in history + +## Related + +- **[API Request](/docs/03-objectui/actions/api-request)** - Navigate after API calls +- **[Page](/docs/03-objectui/container-components/page)** - Page component diff --git a/content/docs/03-objectui/actions/toast.mdx b/content/docs/03-objectui/actions/toast.mdx new file mode 100644 index 0000000..dc56764 --- /dev/null +++ b/content/docs/03-objectui/actions/toast.mdx @@ -0,0 +1,130 @@ +--- +title: Toast +description: Show notification messages +--- + +# Toast + +Show notification messages to users. + +## Protocol + +```typescript +{ + type: 'toast', + message: string, // Message text (template supported) + variant?: 'success' | 'error' | 'warning' | 'info', + duration?: number, // Auto-close duration (ms) +} +``` + +## Examples + +### Success Message + +```json +{ + "type": "toast", + "message": "Operation completed successfully!", + "variant": "success", + "duration": 3000 +} +``` + +### Error Message + +```json +{ + "type": "toast", + "message": "Failed to save changes", + "variant": "error", + "duration": 5000 +} +``` + +### Warning Message + +```json +{ + "type": "toast", + "message": "Please review your changes before submitting", + "variant": "warning" +} +``` + +### Info Message + +```json +{ + "type": "toast", + "message": "Your session will expire in 5 minutes", + "variant": "info", + "duration": 10000 +} +``` + +### After API Call + +```json +{ + "type": "api", + "api": "/api/users", + "method": "POST", + "onSuccess": { + "type": "toast", + "message": "User created: ${response.name}", + "variant": "success" + }, + "onError": { + "type": "toast", + "message": "Error: ${error.message}", + "variant": "error" + } +} +``` + +## Variants + +Toast messages support four variants: + +- **success** - Green checkmark icon, positive feedback +- **error** - Red X icon, error messages +- **warning** - Yellow alert icon, warnings +- **info** - Blue info icon, informational messages + +## Duration + +Control how long the toast appears: + +- Default: `3000ms` (3 seconds) +- Set to `0` for persistent toasts (require manual dismissal) +- Longer for important messages: `5000-10000ms` + +## Template Variables + +Use template syntax for dynamic messages: + +```json +{ + "message": "Welcome back, ${user.name}!", + "variant": "success" +} +``` + +## Multiple Toasts + +Chain multiple toasts: + +```json +{ + "onSuccess": [ + { "type": "toast", "message": "Data saved", "variant": "success" }, + { "type": "toast", "message": "Email sent", "variant": "info" } + ] +} +``` + +## Related + +- **[API Request](/docs/03-objectui/actions/api-request)** - Show feedback after API calls +- **[Form](/docs/03-objectui/container-components/form)** - Form submission feedback diff --git a/content/docs/03-objectui/basic-components/datepicker.mdx b/content/docs/03-objectui/basic-components/datepicker.mdx new file mode 100644 index 0000000..99cbb22 --- /dev/null +++ b/content/docs/03-objectui/basic-components/datepicker.mdx @@ -0,0 +1,117 @@ +--- +title: DatePicker +description: Date and time selection component +--- + +# DatePicker + +Date and time selection component. + +## Protocol + +```typescript +{ + type: 'datepicker', + name: string, + label?: string, + placeholder?: string, + defaultValue?: string | Date, + required?: boolean, + disabled?: boolean, + mode?: 'date' | 'datetime' | 'time' | 'daterange', + format?: string, // Display format (e.g., 'YYYY-MM-DD') + minDate?: string | Date, // Minimum selectable date + maxDate?: string | Date, // Maximum selectable date + disabledDates?: string[], // Array of disabled dates + showTime?: boolean, // Show time picker + onChange?: Action, +} +``` + +## Examples + +### Simple Date + +```json +{ + "type": "datepicker", + "name": "birthday", + "label": "Date of Birth", + "mode": "date", + "maxDate": "today", + "required": true +} +``` + +### DateTime + +```json +{ + "type": "datepicker", + "name": "appointment", + "label": "Appointment Time", + "mode": "datetime", + "format": "YYYY-MM-DD HH:mm", + "minDate": "today", + "showTime": true +} +``` + +### Date Range + +```json +{ + "type": "datepicker", + "name": "dateRange", + "label": "Select Period", + "mode": "daterange", + "defaultValue": { + "start": "2024-01-01", + "end": "2024-12-31" + } +} +``` + +### Time Only + +```json +{ + "type": "datepicker", + "name": "meetingTime", + "label": "Meeting Time", + "mode": "time", + "format": "HH:mm" +} +``` + +## Modes + +The DatePicker supports four modes: + +- **date** - Date selection only +- **datetime** - Date and time selection +- **time** - Time selection only +- **daterange** - Select a date range (start and end dates) + +## Date Constraints + +Control which dates users can select: + +- **minDate** - Earliest selectable date (use "today" for current date) +- **maxDate** - Latest selectable date +- **disabledDates** - Array of specific dates to disable + +## Format Strings + +Common format patterns: + +- `YYYY-MM-DD` - 2024-01-15 +- `YYYY/MM/DD` - 2024/01/15 +- `DD/MM/YYYY` - 15/01/2024 +- `YYYY-MM-DD HH:mm` - 2024-01-15 14:30 +- `HH:mm` - 14:30 + +## Related Components + +- **[Input](/docs/03-objectui/basic-components/input)** - For text entry +- **[Form](/docs/03-objectui/container-components/form)** - Form container diff --git a/content/docs/03-objectui/basic-components/index.mdx b/content/docs/03-objectui/basic-components/index.mdx new file mode 100644 index 0000000..bbce21a --- /dev/null +++ b/content/docs/03-objectui/basic-components/index.mdx @@ -0,0 +1,49 @@ +--- +title: Basic Components +description: Fundamental form and input components in ObjectUI +--- + +# Basic Components + +Basic components are the fundamental building blocks for forms and data input. + +## Component List + +- **[Input](/docs/03-objectui/basic-components/input)** - Text input field for single-line text entry +- **[Select](/docs/03-objectui/basic-components/select)** - Dropdown selection field +- **[DatePicker](/docs/03-objectui/basic-components/datepicker)** - Date and time selection component +- **[Switch](/docs/03-objectui/basic-components/switch)** - Toggle switch for boolean values + +## Overview + +Basic components handle user data entry through various input types. They support: + +- **Validation**: Built-in validation rules and custom patterns +- **Event Handling**: onChange events for real-time interactions +- **API Integration**: Dynamic data loading and dependent fields +- **Accessibility**: Keyboard navigation and screen reader support + +## Common Properties + +All basic components share these common properties: + +```typescript +{ + name: string, // Field identifier + label?: string, // Display label + placeholder?: string, // Placeholder text + defaultValue?: any, // Initial value + required?: boolean, // Required validation + disabled?: boolean, // Disabled state + onChange?: Action, // Change event handler +} +``` + +## Next Steps + +Explore individual components for detailed protocol definitions and examples: + +- **[Input](/docs/03-objectui/basic-components/input)** - Single-line text entry +- **[Select](/docs/03-objectui/basic-components/select)** - Dropdown selection +- **[DatePicker](/docs/03-objectui/basic-components/datepicker)** - Date/time picker +- **[Switch](/docs/03-objectui/basic-components/switch)** - Boolean toggle diff --git a/content/docs/03-objectui/basic-components/input.mdx b/content/docs/03-objectui/basic-components/input.mdx new file mode 100644 index 0000000..a035aa8 --- /dev/null +++ b/content/docs/03-objectui/basic-components/input.mdx @@ -0,0 +1,105 @@ +--- +title: Input +description: Text input field for single-line text entry +--- + +# Input + +Text input field for single-line text entry. + +## Protocol + +```typescript +{ + type: 'input', + name: string, // Field name + label?: string, // Display label + placeholder?: string, // Placeholder text + defaultValue?: string, // Default value + required?: boolean, // Required validation + disabled?: boolean, // Disabled state + maxLength?: number, // Maximum length + minLength?: number, // Minimum length + pattern?: string, // Regex pattern + inputType?: 'text' | 'email' | 'password' | 'url' | 'tel' | 'number', + onChange?: Action, // Change event handler +} +``` + +## Examples + +### Basic Input + +```json +{ + "type": "input", + "name": "email", + "label": "Email Address", + "placeholder": "user@example.com", + "inputType": "email", + "required": true, + "maxLength": 255 +} +``` + +### Password Input + +```json +{ + "type": "input", + "name": "password", + "label": "Password", + "inputType": "password", + "required": true, + "minLength": 8, + "pattern": "^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d).+$" +} +``` + +### Dependent Fields + +```json +{ + "type": "form", + "fields": [ + { + "type": "input", + "name": "username", + "label": "Username", + "required": true, + "onChange": { + "type": "api", + "api": "/api/check-username", + "method": "POST", + "data": { "username": "${value}" } + } + } + ] +} +``` + +## Input Types + +The `inputType` property supports the following values: + +- **text** (default) - Plain text input +- **email** - Email address with validation +- **password** - Masked password input +- **url** - URL with validation +- **tel** - Telephone number +- **number** - Numeric input with increment/decrement + +## Validation + +Input supports multiple validation options: + +- **required** - Field must have a value +- **maxLength** - Maximum character length +- **minLength** - Minimum character length +- **pattern** - Regular expression pattern for custom validation + +## Related Components + +- **[Select](/docs/03-objectui/basic-components/select)** - For predefined options +- **[DatePicker](/docs/03-objectui/basic-components/datepicker)** - For date/time input +- **[Form](/docs/03-objectui/container-components/form)** - Form container diff --git a/content/docs/03-objectui/basic-components/meta.json b/content/docs/03-objectui/basic-components/meta.json new file mode 100644 index 0000000..e3ebd2a --- /dev/null +++ b/content/docs/03-objectui/basic-components/meta.json @@ -0,0 +1,10 @@ +{ + "title": "Basic Components", + "pages": [ + "index", + "input", + "select", + "datepicker", + "switch" + ] +} diff --git a/content/docs/03-objectui/basic-components/select.mdx b/content/docs/03-objectui/basic-components/select.mdx new file mode 100644 index 0000000..ff0fa77 --- /dev/null +++ b/content/docs/03-objectui/basic-components/select.mdx @@ -0,0 +1,128 @@ +--- +title: Select +description: Dropdown selection field +--- + +# Select + +Dropdown selection field. + +## Protocol + +```typescript +{ + type: 'select', + name: string, + label?: string, + placeholder?: string, + defaultValue?: string | number, + required?: boolean, + disabled?: boolean, + multiple?: boolean, // Allow multiple selections + searchable?: boolean, // Enable search/filter + clearable?: boolean, // Show clear button + options?: Array<{ // Static options + label: string, + value: string | number, + disabled?: boolean + }>, + api?: string, // API endpoint for dynamic options + optionLabel?: string, // Field name for option label + optionValue?: string, // Field name for option value + dependsOn?: string, // Field dependency + onChange?: Action, +} +``` + +## Examples + +### Static Options + +```json +{ + "type": "select", + "name": "status", + "label": "Status", + "placeholder": "Select status", + "required": true, + "options": [ + { "label": "Active", "value": "active" }, + { "label": "Inactive", "value": "inactive" }, + { "label": "Pending", "value": "pending" } + ] +} +``` + +### Dynamic Options from API + +```json +{ + "type": "select", + "name": "category", + "label": "Category", + "api": "/api/categories", + "optionLabel": "name", + "optionValue": "id", + "searchable": true +} +``` + +### Dependent Select + +```json +{ + "type": "form", + "fields": [ + { + "type": "select", + "name": "country", + "label": "Country", + "api": "/api/countries" + }, + { + "type": "select", + "name": "state", + "label": "State", + "api": "/api/states?country=${country}", + "dependsOn": "country" + } + ] +} +``` + +### Multiple Selection + +```json +{ + "type": "select", + "name": "tags", + "label": "Tags", + "multiple": true, + "searchable": true, + "options": [ + { "label": "Important", "value": "important" }, + { "label": "Urgent", "value": "urgent" }, + { "label": "Review", "value": "review" } + ] +} +``` + +## Features + +### Static vs Dynamic Options + +- **Static options** - Use the `options` array for predefined choices +- **Dynamic options** - Use `api` to fetch options from a backend endpoint + +### Search and Filter + +Enable `searchable: true` to allow users to filter options by typing. + +### Dependent Fields + +Use `dependsOn` to create cascading selects where one field's options depend on another field's value. + +## Related Components + +- **[Input](/docs/03-objectui/basic-components/input)** - For text entry +- **[Form](/docs/03-objectui/container-components/form)** - Form container diff --git a/content/docs/03-objectui/basic-components/switch.mdx b/content/docs/03-objectui/basic-components/switch.mdx new file mode 100644 index 0000000..c1e8327 --- /dev/null +++ b/content/docs/03-objectui/basic-components/switch.mdx @@ -0,0 +1,101 @@ +--- +title: Switch +description: Toggle switch for boolean values +--- + +# Switch + +Toggle switch for boolean values. + +## Protocol + +```typescript +{ + type: 'switch', + name: string, + label?: string, + defaultValue?: boolean, + disabled?: boolean, + checkedText?: string, // Text when checked + uncheckedText?: string, // Text when unchecked + onChange?: Action, +} +``` + +## Examples + +### Basic Switch + +```json +{ + "type": "switch", + "name": "isActive", + "label": "Active Status", + "defaultValue": true, + "checkedText": "Active", + "uncheckedText": "Inactive" +} +``` + +### Simple Toggle + +```json +{ + "type": "switch", + "name": "notifications", + "label": "Enable Notifications", + "defaultValue": false +} +``` + +### With Change Handler + +```json +{ + "type": "switch", + "name": "autoSave", + "label": "Auto-Save", + "defaultValue": true, + "onChange": { + "type": "api", + "api": "/api/settings/auto-save", + "method": "POST", + "data": { "enabled": "${value}" } + } +} +``` + +## Features + +### State Labels + +Use `checkedText` and `uncheckedText` to provide visual feedback about the current state: + +```json +{ + "type": "switch", + "name": "visibility", + "label": "Post Visibility", + "checkedText": "Public", + "uncheckedText": "Private" +} +``` + +### Default State + +Set `defaultValue: true` to make the switch checked by default, or `false` for unchecked. + +## Use Cases + +Switches are ideal for: + +- Enabling/disabling features +- Toggling visibility +- Activating/deactivating settings +- Binary choices (yes/no, on/off) + +## Related Components + +- **[Input](/docs/03-objectui/basic-components/input)** - For text entry +- **[Select](/docs/03-objectui/basic-components/select)** - For multiple options +- **[Form](/docs/03-objectui/container-components/form)** - Form container diff --git a/content/docs/03-objectui/component-spec.mdx b/content/docs/03-objectui/component-spec.mdx index 3986757..77e0133 100644 --- a/content/docs/03-objectui/component-spec.mdx +++ b/content/docs/03-objectui/component-spec.mdx @@ -5,783 +5,88 @@ description: Complete protocol reference for all ObjectUI components # Component Specification -This comprehensive reference documents all ObjectUI components and their JSON protocols. +This comprehensive reference documents all ObjectUI components and their JSON protocols. The specification is organized into three main categories for easy navigation. -## Basic Components +## Overview -Basic components are the fundamental building blocks for forms and data input. +ObjectUI uses a JSON-based protocol to define user interfaces declaratively. Each component has a specific type and set of properties that control its appearance and behavior. -### Input +## Component Categories -Text input field for single-line text entry. +### Basic Components -**Protocol:** +Form and input components that handle user data entry. -```typescript -{ - type: 'input', - name: string, // Field name - label?: string, // Display label - placeholder?: string, // Placeholder text - defaultValue?: string, // Default value - required?: boolean, // Required validation - disabled?: boolean, // Disabled state - maxLength?: number, // Maximum length - minLength?: number, // Minimum length - pattern?: string, // Regex pattern - inputType?: 'text' | 'email' | 'password' | 'url' | 'tel' | 'number', - onChange?: Action, // Change event handler -} -``` - -**Example:** - -```json -{ - "type": "input", - "name": "email", - "label": "Email Address", - "placeholder": "user@example.com", - "inputType": "email", - "required": true, - "maxLength": 255 -} -``` - -**Advanced Example - Dependent Fields:** - -```json -{ - "type": "form", - "fields": [ - { - "type": "input", - "name": "username", - "label": "Username", - "required": true, - "onChange": { - "type": "api", - "api": "/api/check-username", - "method": "POST", - "data": { "username": "${value}" } - } - } - ] -} -``` - -### Select - -Dropdown selection field. - -**Protocol:** - -```typescript -{ - type: 'select', - name: string, - label?: string, - placeholder?: string, - defaultValue?: string | number, - required?: boolean, - disabled?: boolean, - multiple?: boolean, // Allow multiple selections - searchable?: boolean, // Enable search/filter - clearable?: boolean, // Show clear button - options?: Array<{ // Static options - label: string, - value: string | number, - disabled?: boolean - }>, - api?: string, // API endpoint for dynamic options - optionLabel?: string, // Field name for option label - optionValue?: string, // Field name for option value - dependsOn?: string, // Field dependency - onChange?: Action, -} -``` - -**Example - Static Options:** - -```json -{ - "type": "select", - "name": "status", - "label": "Status", - "placeholder": "Select status", - "required": true, - "options": [ - { "label": "Active", "value": "active" }, - { "label": "Inactive", "value": "inactive" }, - { "label": "Pending", "value": "pending" } - ] -} -``` +**Includes:** Input, Select, DatePicker, Switch -**Example - Dynamic Options from API:** +→ **[View Basic Components](/docs/03-objectui/basic-components)** -```json -{ - "type": "select", - "name": "category", - "label": "Category", - "api": "/api/categories", - "optionLabel": "name", - "optionValue": "id", - "searchable": true -} -``` +### Container Components -**Example - Dependent Select:** +Layout and structural components that organize the UI. -```json -{ - "type": "form", - "fields": [ - { - "type": "select", - "name": "country", - "label": "Country", - "api": "/api/countries" - }, - { - "type": "select", - "name": "state", - "label": "State", - "api": "/api/states?country=${country}", - "dependsOn": "country" - } - ] -} -``` +**Includes:** Page, Grid, Card, Form, Table -### DatePicker +→ **[View Container Components](/docs/03-objectui/container-components)** -Date and time selection component. +### Actions -**Protocol:** +Interactive behaviors and event handlers. -```typescript -{ - type: 'datepicker', - name: string, - label?: string, - placeholder?: string, - defaultValue?: string | Date, - required?: boolean, - disabled?: boolean, - mode?: 'date' | 'datetime' | 'time' | 'daterange', - format?: string, // Display format (e.g., 'YYYY-MM-DD') - minDate?: string | Date, // Minimum selectable date - maxDate?: string | Date, // Maximum selectable date - disabledDates?: string[], // Array of disabled dates - showTime?: boolean, // Show time picker - onChange?: Action, -} -``` +**Includes:** API Request, Navigate, Dialog, Toast -**Example - Simple Date:** +→ **[View Actions](/docs/03-objectui/actions)** -```json -{ - "type": "datepicker", - "name": "birthday", - "label": "Date of Birth", - "mode": "date", - "maxDate": "today", - "required": true -} -``` - -**Example - DateTime:** - -```json -{ - "type": "datepicker", - "name": "appointment", - "label": "Appointment Time", - "mode": "datetime", - "format": "YYYY-MM-DD HH:mm", - "minDate": "today", - "showTime": true -} -``` +## Quick Example -**Example - Date Range:** - -```json -{ - "type": "datepicker", - "name": "dateRange", - "label": "Select Period", - "mode": "daterange", - "defaultValue": { - "start": "2024-01-01", - "end": "2024-12-31" - } -} -``` - -### Switch - -Toggle switch for boolean values. - -**Protocol:** - -```typescript -{ - type: 'switch', - name: string, - label?: string, - defaultValue?: boolean, - disabled?: boolean, - checkedText?: string, // Text when checked - uncheckedText?: string, // Text when unchecked - onChange?: Action, -} -``` - -**Example:** - -```json -{ - "type": "switch", - "name": "isActive", - "label": "Active Status", - "defaultValue": true, - "checkedText": "Active", - "uncheckedText": "Inactive" -} -``` - -## Container Components - -Container components organize and structure the UI layout. - -### Page - -Top-level page container with header and actions. - -**Protocol:** - -```typescript -{ - type: 'page', - title: string, - description?: string, - icon?: string, - breadcrumbs?: Array<{ - label: string, - url?: string - }>, - actions?: Action[], // Header actions - tabs?: Array<{ - label: string, - key: string, - body: Component - }>, - body: Component | Component[], -} -``` - -**Example:** +Here's a simple example combining different component types: ```json { "type": "page", - "title": "User Management", - "description": "Manage system users and permissions", - "breadcrumbs": [ - { "label": "Home", "url": "/" }, - { "label": "Users" } - ], - "actions": [ - { - "label": "Add User", - "type": "dialog", - "body": { - "type": "form", - "api": "/api/users", - "fields": [...] - } - } - ], - "body": { - "type": "table", - "api": "/api/users" - } -} -``` - -### Grid - -Responsive grid layout. - -**Protocol:** - -```typescript -{ - type: 'grid', - columns?: number | { // Column configuration - xs?: number, // Extra small devices - sm?: number, // Small devices - md?: number, // Medium devices - lg?: number, // Large devices - xl?: number // Extra large devices - }, - gap?: number | string, // Gap between items - items: Component[], -} -``` - -**Example:** - -```json -{ - "type": "grid", - "columns": { "xs": 1, "sm": 2, "lg": 3 }, - "gap": "20px", - "items": [ - { - "type": "card", - "title": "Total Users", - "body": { "type": "text", "value": "${stats.users}" } - }, - { - "type": "card", - "title": "Total Orders", - "body": { "type": "text", "value": "${stats.orders}" } - }, - { - "type": "card", - "title": "Revenue", - "body": { "type": "text", "value": "$${stats.revenue}" } - } - ] -} -``` - -### Card - -Card container with header, body, and footer. - -**Protocol:** - -```typescript -{ - type: 'card', - title?: string, - description?: string, - cover?: string, // Cover image URL - avatar?: string, // Avatar image URL - actions?: Action[], - body: Component | Component[], - footer?: Component | Component[], -} -``` - -**Example:** - -```json -{ - "type": "card", "title": "User Profile", - "avatar": "${user.avatar}", - "body": [ - { "type": "text", "value": "Name: ${user.name}" }, - { "type": "text", "value": "Email: ${user.email}" }, - { "type": "text", "value": "Role: ${user.role}" } - ], - "actions": [ - { "label": "Edit", "onClick": { "type": "navigate", "url": "/users/${user.id}/edit" } }, - { "label": "Delete", "onClick": { "type": "api", "api": "/api/users/${user.id}", "method": "DELETE" } } - ] -} -``` - -### Form - -Form container with fields and submission handling. - -**Protocol:** - -```typescript -{ - type: 'form', - title?: string, - api?: string, // Submit endpoint - method?: 'POST' | 'PUT' | 'PATCH', - initialValues?: object, // Initial form values - fields: FormField[], - layout?: 'horizontal' | 'vertical' | 'inline', - columns?: number, // Multi-column layout - submitText?: string, // Submit button text - resetText?: string, // Reset button text - showReset?: boolean, // Show reset button - onSubmit?: Action, - onSuccess?: Action, - onError?: Action, -} -``` - -**Example - Simple Form:** - -```json -{ - "type": "form", - "title": "Create User", - "api": "/api/users", - "method": "POST", - "fields": [ - { - "type": "input", - "name": "name", - "label": "Full Name", - "required": true - }, - { - "type": "input", - "name": "email", - "label": "Email", - "inputType": "email", - "required": true - }, - { - "type": "select", - "name": "role", - "label": "Role", - "options": [ - { "label": "Admin", "value": "admin" }, - { "label": "User", "value": "user" } - ] - } - ], - "submitText": "Create User", - "onSuccess": { - "type": "toast", - "message": "User created successfully!" - } -} -``` - -**Example - Multi-column Form:** - -```json -{ - "type": "form", - "title": "User Registration", - "columns": 2, - "fields": [ - { "type": "input", "name": "firstName", "label": "First Name" }, - { "type": "input", "name": "lastName", "label": "Last Name" }, - { "type": "input", "name": "email", "label": "Email", "inputType": "email" }, - { "type": "input", "name": "phone", "label": "Phone", "inputType": "tel" }, - { "type": "datepicker", "name": "birthday", "label": "Birthday" }, - { "type": "select", "name": "country", "label": "Country", "api": "/api/countries" } - ] -} -``` - -### Table - -Data table with sorting, filtering, and pagination. - -**Protocol:** - -```typescript -{ - type: 'table', - api?: string, // Data endpoint - data?: any[], // Static data - columns: Array<{ - name: string, - label: string, - type?: 'text' | 'number' | 'boolean' | 'date' | 'image', - sortable?: boolean, - filterable?: boolean, - width?: number | string, - render?: string, // Custom render template - }>, - rowActions?: Action[], // Actions per row - batchActions?: Action[], // Batch actions - pagination?: boolean, - pageSize?: number, - searchable?: boolean, // Global search - filters?: Array<{ - name: string, - label: string, - type: 'input' | 'select' | 'datepicker' - }>, - selectable?: boolean, // Row selection - expandable?: Component, // Expandable row content -} -``` - -**Example - Basic Table:** - -```json -{ - "type": "table", - "api": "/api/users", - "columns": [ - { "name": "id", "label": "ID", "width": 80 }, - { "name": "name", "label": "Name", "sortable": true }, - { "name": "email", "label": "Email", "sortable": true }, - { "name": "role", "label": "Role", "filterable": true }, - { "name": "createdAt", "label": "Created", "type": "date", "sortable": true } - ], - "rowActions": [ - { "label": "Edit", "onClick": { "type": "navigate", "url": "/users/${id}/edit" } }, - { "label": "Delete", "onClick": { "type": "api", "api": "/api/users/${id}", "method": "DELETE", "confirm": "Delete this user?" } } - ], - "pagination": true, - "pageSize": 20, - "searchable": true -} -``` - -**Example - CRUD Table:** - -```json -{ - "type": "table", - "api": "/api/products", - "columns": [ - { "name": "name", "label": "Product Name" }, - { "name": "price", "label": "Price", "type": "number" }, - { "name": "stock", "label": "Stock", "type": "number" }, - { "name": "active", "label": "Active", "type": "boolean" } - ], - "filters": [ - { "name": "category", "label": "Category", "type": "select", "api": "/api/categories" }, - { "name": "priceRange", "label": "Price Range", "type": "input" } - ], - "selectable": true, - "batchActions": [ - { "label": "Delete Selected", "onClick": { "type": "api", "api": "/api/products/batch-delete", "method": "POST" } }, - { "label": "Export", "onClick": { "type": "download", "url": "/api/products/export" } } - ], - "rowActions": [ - { "label": "Edit", "onClick": { "type": "dialog", "title": "Edit Product", "body": { "type": "form", "fields": [...] } } }, - { "label": "Delete", "onClick": { "type": "api", "api": "/api/products/${id}", "method": "DELETE" } } - ] -} -``` - -## Actions - -Actions define interactive behaviors in ObjectUI. - -### API Request - -Make HTTP requests. - -**Protocol:** - -```typescript -{ - type: 'api', - api: string, // API endpoint - method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE', - data?: object | string, // Request body (template supported) - headers?: object, // Request headers - confirm?: string, // Confirmation message - onSuccess?: Action, // Success handler - onError?: Action, // Error handler -} -``` - -**Example:** - -```json -{ - "type": "button", - "label": "Save", - "onClick": { - "type": "api", - "api": "/api/users/${userId}", - "method": "PUT", - "data": "${formData}", - "confirm": "Save changes?", - "onSuccess": { - "type": "toast", - "message": "Saved successfully!" - } - } -} -``` - -### Navigate - -Navigate to a different page. - -**Protocol:** - -```typescript -{ - type: 'navigate', - url: string, // Target URL (template supported) - newTab?: boolean, // Open in new tab - replace?: boolean, // Replace current history entry -} -``` - -**Example:** - -```json -{ - "type": "button", - "label": "View Details", - "onClick": { - "type": "navigate", - "url": "/users/${userId}" - } -} -``` - -### Dialog - -Open a modal dialog. - -**Protocol:** - -```typescript -{ - type: 'dialog', - title?: string, - width?: number | string, - body: Component, - footer?: Component[], - closable?: boolean, -} -``` - -**Example:** - -```json -{ - "type": "button", - "label": "Add User", - "onClick": { - "type": "dialog", - "title": "Create New User", - "width": 600, - "body": { - "type": "form", - "api": "/api/users", - "fields": [...] - } - } -} -``` - -### Toast - -Show notification message. - -**Protocol:** - -```typescript -{ - type: 'toast', - message: string, // Message text (template supported) - variant?: 'success' | 'error' | 'warning' | 'info', - duration?: number, // Auto-close duration (ms) -} -``` - -**Example:** - -```json -{ - "type": "toast", - "message": "Operation completed successfully!", - "variant": "success", - "duration": 3000 -} -``` - -## Complete Examples - -### User Management CRUD - -```json -{ - "type": "page", - "title": "User Management", - "actions": [ - { - "label": "Add User", - "onClick": { - "type": "dialog", - "title": "Create User", - "body": { - "type": "form", - "api": "/api/users", - "method": "POST", - "fields": [ - { "type": "input", "name": "name", "label": "Name", "required": true }, - { "type": "input", "name": "email", "label": "Email", "inputType": "email", "required": true }, - { "type": "select", "name": "role", "label": "Role", "options": [ - { "label": "Admin", "value": "admin" }, - { "label": "User", "value": "user" } - ]} - ], - "onSuccess": [ - { "type": "toast", "message": "User created!" }, - { "type": "reload" } - ] - } - } - } - ], "body": { - "type": "table", + "type": "form", "api": "/api/users", - "columns": [ - { "name": "name", "label": "Name", "sortable": true }, - { "name": "email", "label": "Email" }, - { "name": "role", "label": "Role" }, - { "name": "createdAt", "label": "Created", "type": "date" } - ], - "rowActions": [ + "fields": [ { - "label": "Edit", - "onClick": { - "type": "dialog", - "title": "Edit User", - "body": { - "type": "form", - "api": "/api/users/${id}", - "method": "PUT", - "initialValues": "${row}", - "fields": [ - { "type": "input", "name": "name", "label": "Name" }, - { "type": "input", "name": "email", "label": "Email" } - ] - } - } + "type": "input", + "name": "name", + "label": "Full Name", + "required": true }, { - "label": "Delete", - "onClick": { - "type": "api", - "api": "/api/users/${id}", - "method": "DELETE", - "confirm": "Delete this user?", - "onSuccess": [ - { "type": "toast", "message": "User deleted" }, - { "type": "reload" } - ] - } + "type": "select", + "name": "role", + "label": "Role", + "options": [ + { "label": "Admin", "value": "admin" }, + { "label": "User", "value": "user" } + ] } ], - "searchable": true, - "pagination": true + "onSuccess": { + "type": "toast", + "message": "Profile updated!" + } } } ``` +## Component Features + +All ObjectUI components support: + +- **Protocol-Driven**: Pure JSON configuration +- **Type Safety**: TypeScript definitions available +- **Template Support**: Dynamic values with `${variable}` syntax +- **Event Handling**: Flexible action system +- **Validation**: Built-in form validation +- **API Integration**: Native support for REST APIs + ## Next Steps -- **[Renderer Usage](/docs/03-objectui/renderer-usage)** - Learn how to integrate these components in your application +- **[Basic Components](/docs/03-objectui/basic-components)** - Learn about form and input components +- **[Container Components](/docs/03-objectui/container-components)** - Explore layout components +- **[Actions](/docs/03-objectui/actions)** - Understand interactive behaviors +- **[Renderer Usage](/docs/03-objectui/renderer-usage)** - Learn how to integrate components in your application diff --git a/content/docs/03-objectui/container-components/card.mdx b/content/docs/03-objectui/container-components/card.mdx new file mode 100644 index 0000000..c99ae96 --- /dev/null +++ b/content/docs/03-objectui/container-components/card.mdx @@ -0,0 +1,111 @@ +--- +title: Card +description: Card container with header, body, and footer +--- + +# Card + +Card container with header, body, and footer. + +## Protocol + +```typescript +{ + type: 'card', + title?: string, + description?: string, + cover?: string, // Cover image URL + avatar?: string, // Avatar image URL + actions?: Action[], + body: Component | Component[], + footer?: Component | Component[], +} +``` + +## Examples + +### Basic Card + +```json +{ + "type": "card", + "title": "User Profile", + "avatar": "${user.avatar}", + "body": [ + { "type": "text", "value": "Name: ${user.name}" }, + { "type": "text", "value": "Email: ${user.email}" }, + { "type": "text", "value": "Role: ${user.role}" } + ], + "actions": [ + { "label": "Edit", "onClick": { "type": "navigate", "url": "/users/${user.id}/edit" } }, + { "label": "Delete", "onClick": { "type": "api", "api": "/api/users/${user.id}", "method": "DELETE" } } + ] +} +``` + +### Card with Cover Image + +```json +{ + "type": "card", + "title": "Product", + "description": "Premium wireless headphones", + "cover": "/images/product.jpg", + "body": { + "type": "text", + "value": "$299.99" + }, + "actions": [ + { "label": "Buy Now", "onClick": {...} } + ] +} +``` + +### Stats Card + +```json +{ + "type": "card", + "title": "Total Sales", + "body": { + "type": "text", + "value": "$${stats.totalSales}", + "style": "text-3xl font-bold" + }, + "footer": { + "type": "text", + "value": "↑ 12% from last month" + } +} +``` + +## Features + +### Header + +Cards can have a title, description, and avatar/cover image in the header. + +### Body + +The body can contain any component or array of components. + +### Footer + +Optional footer for additional content or metadata. + +### Actions + +Action buttons appear in the card's action area. + +## Use Cases + +- User profiles +- Product listings +- Statistics/metrics +- Content previews +- Settings panels + +## Related Components + +- **[Grid](/docs/03-objectui/container-components/grid)** - Card layouts +- **[Page](/docs/03-objectui/container-components/page)** - Page container diff --git a/content/docs/03-objectui/container-components/form.mdx b/content/docs/03-objectui/container-components/form.mdx new file mode 100644 index 0000000..80e7a9b --- /dev/null +++ b/content/docs/03-objectui/container-components/form.mdx @@ -0,0 +1,143 @@ +--- +title: Form +description: Form container with fields and submission handling +--- + +# Form + +Form container with fields and submission handling. + +## Protocol + +```typescript +{ + type: 'form', + title?: string, + api?: string, // Submit endpoint + method?: 'POST' | 'PUT' | 'PATCH', + initialValues?: object, // Initial form values + fields: FormField[], + layout?: 'horizontal' | 'vertical' | 'inline', + columns?: number, // Multi-column layout + submitText?: string, // Submit button text + resetText?: string, // Reset button text + showReset?: boolean, // Show reset button + onSubmit?: Action, + onSuccess?: Action, + onError?: Action, +} +``` + +## Examples + +### Simple Form + +```json +{ + "type": "form", + "title": "Create User", + "api": "/api/users", + "method": "POST", + "fields": [ + { + "type": "input", + "name": "name", + "label": "Full Name", + "required": true + }, + { + "type": "input", + "name": "email", + "label": "Email", + "inputType": "email", + "required": true + }, + { + "type": "select", + "name": "role", + "label": "Role", + "options": [ + { "label": "Admin", "value": "admin" }, + { "label": "User", "value": "user" } + ] + } + ], + "submitText": "Create User", + "onSuccess": { + "type": "toast", + "message": "User created successfully!" + } +} +``` + +### Multi-column Form + +```json +{ + "type": "form", + "title": "User Registration", + "columns": 2, + "fields": [ + { "type": "input", "name": "firstName", "label": "First Name" }, + { "type": "input", "name": "lastName", "label": "Last Name" }, + { "type": "input", "name": "email", "label": "Email", "inputType": "email" }, + { "type": "input", "name": "phone", "label": "Phone", "inputType": "tel" }, + { "type": "datepicker", "name": "birthday", "label": "Birthday" }, + { "type": "select", "name": "country", "label": "Country", "api": "/api/countries" } + ] +} +``` + +### Edit Form with Initial Values + +```json +{ + "type": "form", + "title": "Edit User", + "api": "/api/users/${userId}", + "method": "PUT", + "initialValues": { + "name": "John Doe", + "email": "john@example.com", + "role": "admin" + }, + "fields": [...] +} +``` + +## Features + +### Layouts + +Forms support three layout modes: + +- **vertical** (default) - Labels above fields +- **horizontal** - Labels beside fields +- **inline** - Fields in a single row + +### Multi-column + +Use `columns` to create multi-column layouts for better space utilization. + +### Validation + +Forms automatically validate fields based on their `required`, `pattern`, `minLength`, and `maxLength` properties. + +### Submission + +Forms can submit to an API endpoint or trigger custom actions via `onSubmit`. + +## Field Types + +Forms can contain any basic component: + +- [Input](/docs/03-objectui/basic-components/input) +- [Select](/docs/03-objectui/basic-components/select) +- [DatePicker](/docs/03-objectui/basic-components/datepicker) +- [Switch](/docs/03-objectui/basic-components/switch) + +## Related Components + +- **[Input](/docs/03-objectui/basic-components/input)** - Text input +- **[Select](/docs/03-objectui/basic-components/select)** - Dropdown +- **[Page](/docs/03-objectui/container-components/page)** - Page container diff --git a/content/docs/03-objectui/container-components/grid.mdx b/content/docs/03-objectui/container-components/grid.mdx new file mode 100644 index 0000000..6dbfac3 --- /dev/null +++ b/content/docs/03-objectui/container-components/grid.mdx @@ -0,0 +1,108 @@ +--- +title: Grid +description: Responsive grid layout +--- + +# Grid + +Responsive grid layout. + +## Protocol + +```typescript +{ + type: 'grid', + columns?: number | { // Column configuration + xs?: number, // Extra small devices + sm?: number, // Small devices + md?: number, // Medium devices + lg?: number, // Large devices + xl?: number // Extra large devices + }, + gap?: number | string, // Gap between items + items: Component[], +} +``` + +## Examples + +### Responsive Grid + +```json +{ + "type": "grid", + "columns": { "xs": 1, "sm": 2, "lg": 3 }, + "gap": "20px", + "items": [ + { + "type": "card", + "title": "Total Users", + "body": { "type": "text", "value": "${stats.users}" } + }, + { + "type": "card", + "title": "Total Orders", + "body": { "type": "text", "value": "${stats.orders}" } + }, + { + "type": "card", + "title": "Revenue", + "body": { "type": "text", "value": "$${stats.revenue}" } + } + ] +} +``` + +### Fixed Columns + +```json +{ + "type": "grid", + "columns": 4, + "gap": "16px", + "items": [...] +} +``` + +## Responsive Breakpoints + +The grid supports five breakpoint sizes: + +- **xs** - Extra small (<576px) - Mobile portrait +- **sm** - Small (≥576px) - Mobile landscape +- **md** - Medium (≥768px) - Tablet +- **lg** - Large (≥992px) - Desktop +- **xl** - Extra large (≥1200px) - Large desktop + +## Layout Patterns + +### Dashboard Cards + +```json +{ + "type": "grid", + "columns": { "xs": 1, "md": 2, "xl": 4 }, + "items": [ + { "type": "card", "title": "Metric 1", "body": {...} }, + { "type": "card", "title": "Metric 2", "body": {...} }, + { "type": "card", "title": "Metric 3", "body": {...} }, + { "type": "card", "title": "Metric 4", "body": {...} } + ] +} +``` + +### Product Gallery + +```json +{ + "type": "grid", + "columns": { "xs": 2, "sm": 3, "lg": 4 }, + "gap": "24px", + "items": [...] +} +``` + +## Related Components + +- **[Card](/docs/03-objectui/container-components/card)** - Grid items +- **[Page](/docs/03-objectui/container-components/page)** - Page container diff --git a/content/docs/03-objectui/container-components/index.mdx b/content/docs/03-objectui/container-components/index.mdx new file mode 100644 index 0000000..6b43be3 --- /dev/null +++ b/content/docs/03-objectui/container-components/index.mdx @@ -0,0 +1,74 @@ +--- +title: Container Components +description: Layout and structural components in ObjectUI +--- + +# Container Components + +Container components organize and structure the UI layout. + +## Component List + +- **[Page](/docs/03-objectui/container-components/page)** - Top-level page container +- **[Grid](/docs/03-objectui/container-components/grid)** - Responsive grid layout +- **[Card](/docs/03-objectui/container-components/card)** - Card container with header, body, and footer +- **[Form](/docs/03-objectui/container-components/form)** - Form container with fields and submission +- **[Table](/docs/03-objectui/container-components/table)** - Data table with sorting, filtering, and pagination + +## Overview + +Container components provide structure and layout capabilities for building complex UIs. They support: + +- **Nested Composition**: Components can contain other components +- **Responsive Design**: Automatic adaptation to different screen sizes +- **Data Binding**: Dynamic content from APIs or state +- **Action Handlers**: Built-in support for user interactions + +## Common Patterns + +### Page Layout + +Pages typically contain a header with actions and a body with content: + +```json +{ + "type": "page", + "title": "Dashboard", + "actions": [...], + "body": {...} +} +``` + +### Grid Layouts + +Use grids for responsive multi-column layouts: + +```json +{ + "type": "grid", + "columns": { "xs": 1, "sm": 2, "lg": 3 }, + "items": [...] +} +``` + +### Forms + +Forms group input fields with submission handling: + +```json +{ + "type": "form", + "fields": [...], + "onSubmit": {...} +} +``` + +## Next Steps + +Explore individual components for detailed protocol definitions and examples: + +- **[Page](/docs/03-objectui/container-components/page)** - Page container +- **[Grid](/docs/03-objectui/container-components/grid)** - Grid layout +- **[Card](/docs/03-objectui/container-components/card)** - Card component +- **[Form](/docs/03-objectui/container-components/form)** - Form container +- **[Table](/docs/03-objectui/container-components/table)** - Data table diff --git a/content/docs/03-objectui/container-components/meta.json b/content/docs/03-objectui/container-components/meta.json new file mode 100644 index 0000000..52b22ef --- /dev/null +++ b/content/docs/03-objectui/container-components/meta.json @@ -0,0 +1,11 @@ +{ + "title": "Container Components", + "pages": [ + "index", + "page", + "grid", + "card", + "form", + "table" + ] +} diff --git a/content/docs/03-objectui/container-components/page.mdx b/content/docs/03-objectui/container-components/page.mdx new file mode 100644 index 0000000..361afb7 --- /dev/null +++ b/content/docs/03-objectui/container-components/page.mdx @@ -0,0 +1,131 @@ +--- +title: Page +description: Top-level page container with header and actions +--- + +# Page + +Top-level page container with header and actions. + +## Protocol + +```typescript +{ + type: 'page', + title: string, + description?: string, + icon?: string, + breadcrumbs?: Array<{ + label: string, + url?: string + }>, + actions?: Action[], // Header actions + tabs?: Array<{ + label: string, + key: string, + body: Component + }>, + body: Component | Component[], +} +``` + +## Examples + +### Basic Page + +```json +{ + "type": "page", + "title": "User Management", + "description": "Manage system users and permissions", + "breadcrumbs": [ + { "label": "Home", "url": "/" }, + { "label": "Users" } + ], + "actions": [ + { + "label": "Add User", + "type": "dialog", + "body": { + "type": "form", + "api": "/api/users", + "fields": [...] + } + } + ], + "body": { + "type": "table", + "api": "/api/users" + } +} +``` + +### Page with Tabs + +```json +{ + "type": "page", + "title": "Settings", + "tabs": [ + { + "label": "General", + "key": "general", + "body": { "type": "form", "fields": [...] } + }, + { + "label": "Security", + "key": "security", + "body": { "type": "form", "fields": [...] } + } + ] +} +``` + +## Features + +### Breadcrumbs + +Breadcrumbs provide navigation context: + +```json +{ + "breadcrumbs": [ + { "label": "Home", "url": "/" }, + { "label": "Products", "url": "/products" }, + { "label": "Edit Product" } + ] +} +``` + +### Header Actions + +Actions appear in the page header: + +```json +{ + "actions": [ + { "label": "New", "onClick": {...} }, + { "label": "Import", "onClick": {...} }, + { "label": "Export", "onClick": {...} } + ] +} +``` + +### Tabs + +Organize content into tabbed sections: + +```json +{ + "tabs": [ + { "label": "Overview", "key": "overview", "body": {...} }, + { "label": "Details", "key": "details", "body": {...} } + ] +} +``` + +## Related Components + +- **[Table](/docs/03-objectui/container-components/table)** - Data display +- **[Form](/docs/03-objectui/container-components/form)** - Data entry +- **[Grid](/docs/03-objectui/container-components/grid)** - Layout diff --git a/content/docs/03-objectui/container-components/table.mdx b/content/docs/03-objectui/container-components/table.mdx new file mode 100644 index 0000000..58560e6 --- /dev/null +++ b/content/docs/03-objectui/container-components/table.mdx @@ -0,0 +1,157 @@ +--- +title: Table +description: Data table with sorting, filtering, and pagination +--- + +# Table + +Data table with sorting, filtering, and pagination. + +## Protocol + +```typescript +{ + type: 'table', + api?: string, // Data endpoint + data?: any[], // Static data + columns: Array<{ + name: string, + label: string, + type?: 'text' | 'number' | 'boolean' | 'date' | 'image', + sortable?: boolean, + filterable?: boolean, + width?: number | string, + render?: string, // Custom render template + }>, + rowActions?: Action[], // Actions per row + batchActions?: Action[], // Batch actions + pagination?: boolean, + pageSize?: number, + searchable?: boolean, // Global search + filters?: Array<{ + name: string, + label: string, + type: 'input' | 'select' | 'datepicker' + }>, + selectable?: boolean, // Row selection + expandable?: Component, // Expandable row content +} +``` + +## Examples + +### Basic Table + +```json +{ + "type": "table", + "api": "/api/users", + "columns": [ + { "name": "id", "label": "ID", "width": 80 }, + { "name": "name", "label": "Name", "sortable": true }, + { "name": "email", "label": "Email", "sortable": true }, + { "name": "role", "label": "Role", "filterable": true }, + { "name": "createdAt", "label": "Created", "type": "date", "sortable": true } + ], + "rowActions": [ + { "label": "Edit", "onClick": { "type": "navigate", "url": "/users/${id}/edit" } }, + { "label": "Delete", "onClick": { "type": "api", "api": "/api/users/${id}", "method": "DELETE", "confirm": "Delete this user?" } } + ], + "pagination": true, + "pageSize": 20, + "searchable": true +} +``` + +### CRUD Table + +```json +{ + "type": "table", + "api": "/api/products", + "columns": [ + { "name": "name", "label": "Product Name" }, + { "name": "price", "label": "Price", "type": "number" }, + { "name": "stock", "label": "Stock", "type": "number" }, + { "name": "active", "label": "Active", "type": "boolean" } + ], + "filters": [ + { "name": "category", "label": "Category", "type": "select", "api": "/api/categories" }, + { "name": "priceRange", "label": "Price Range", "type": "input" } + ], + "selectable": true, + "batchActions": [ + { "label": "Delete Selected", "onClick": { "type": "api", "api": "/api/products/batch-delete", "method": "POST" } }, + { "label": "Export", "onClick": { "type": "download", "url": "/api/products/export" } } + ], + "rowActions": [ + { "label": "Edit", "onClick": { "type": "dialog", "title": "Edit Product", "body": { "type": "form", "fields": [...] } } }, + { "label": "Delete", "onClick": { "type": "api", "api": "/api/products/${id}", "method": "DELETE" } } + ] +} +``` + +### Static Data Table + +```json +{ + "type": "table", + "data": [ + { "id": 1, "name": "Alice", "role": "Admin" }, + { "id": 2, "name": "Bob", "role": "User" } + ], + "columns": [ + { "name": "id", "label": "ID" }, + { "name": "name", "label": "Name" }, + { "name": "role", "label": "Role" } + ] +} +``` + +## Features + +### Columns + +Each column can specify: + +- **type** - Data type for rendering (text, number, boolean, date, image) +- **sortable** - Enable sorting for this column +- **filterable** - Enable filtering for this column +- **width** - Fixed column width + +### Sorting + +Enable sorting on columns with `sortable: true`. Users can click column headers to sort. + +### Filtering + +Add filters for specific columns or use global search with `searchable: true`. + +### Pagination + +Enable pagination with `pagination: true` and set items per page with `pageSize`. + +### Row Actions + +Actions that apply to individual rows (edit, delete, view details, etc.). + +### Batch Actions + +Actions that apply to selected rows when `selectable: true`. + +### Expandable Rows + +Show additional details by setting `expandable` to a component definition. + +## Column Types + +- **text** - Plain text (default) +- **number** - Numeric values with proper alignment +- **boolean** - Checkmark or yes/no indicator +- **date** - Formatted date display +- **image** - Image thumbnail + +## Related Components + +- **[Page](/docs/03-objectui/container-components/page)** - Page container +- **[Form](/docs/03-objectui/container-components/form)** - Edit forms diff --git a/content/docs/03-objectui/meta.json b/content/docs/03-objectui/meta.json index 8ec6a9b..ae2903b 100644 --- a/content/docs/03-objectui/meta.json +++ b/content/docs/03-objectui/meta.json @@ -5,6 +5,9 @@ "index", "core-concepts", "component-spec", + "basic-components", + "container-components", + "actions", "renderer-usage" ] } diff --git a/content/docs/cn/03-objectui/actions/api-request.mdx b/content/docs/cn/03-objectui/actions/api-request.mdx new file mode 100644 index 0000000..ed2d496 --- /dev/null +++ b/content/docs/cn/03-objectui/actions/api-request.mdx @@ -0,0 +1,136 @@ +--- +title: API Request +description: Make HTTP requests +--- + +# API Request + +Make HTTP requests to backend endpoints. + +## Protocol + +```typescript +{ + type: 'api', + api: string, // API endpoint + method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE', + data?: object | string, // Request body (template supported) + headers?: object, // Request headers + confirm?: string, // Confirmation message + onSuccess?: Action, // Success handler + onError?: Action, // Error handler +} +``` + +## Examples + +### Basic Request + +```json +{ + "type": "button", + "label": "Save", + "onClick": { + "type": "api", + "api": "/api/users/${userId}", + "method": "PUT", + "data": "${formData}", + "confirm": "Save changes?", + "onSuccess": { + "type": "toast", + "message": "Saved successfully!" + } + } +} +``` + +### DELETE with Confirmation + +```json +{ + "type": "api", + "api": "/api/users/${id}", + "method": "DELETE", + "confirm": "Are you sure you want to delete this user?", + "onSuccess": [ + { "type": "toast", "message": "User deleted" }, + { "type": "reload" } + ], + "onError": { + "type": "toast", + "message": "Failed to delete user", + "variant": "error" + } +} +``` + +### POST with Custom Headers + +```json +{ + "type": "api", + "api": "/api/upload", + "method": "POST", + "headers": { + "Content-Type": "multipart/form-data" + }, + "data": "${fileData}" +} +``` + +## HTTP Methods + +- **GET** - Retrieve data +- **POST** - Create new resources +- **PUT** - Update entire resources +- **PATCH** - Partial updates +- **DELETE** - Remove resources + +## Template Variables + +Use template syntax in `api`, `data`, and other string fields: + +```json +{ + "api": "/api/users/${userId}/posts/${postId}", + "data": { + "title": "${formData.title}", + "content": "${formData.content}" + } +} +``` + +## Action Chaining + +Chain multiple actions on success or error: + +```json +{ + "type": "api", + "api": "/api/submit", + "method": "POST", + "onSuccess": [ + { "type": "toast", "message": "Success!" }, + { "type": "navigate", "url": "/dashboard" } + ] +} +``` + +## Confirmation Dialogs + +Add a confirmation prompt before executing: + +```json +{ + "type": "api", + "api": "/api/delete-all", + "method": "POST", + "confirm": "This will delete all data. Are you sure?" +} +``` + +## Related + +- **[Form](/docs/03-objectui/container-components/form)** - Form submission +- **[Toast](/docs/03-objectui/actions/toast)** - User feedback +- **[Navigate](/docs/03-objectui/actions/navigate)** - Redirect after API calls diff --git a/content/docs/cn/03-objectui/actions/dialog.mdx b/content/docs/cn/03-objectui/actions/dialog.mdx new file mode 100644 index 0000000..ff06692 --- /dev/null +++ b/content/docs/cn/03-objectui/actions/dialog.mdx @@ -0,0 +1,122 @@ +--- +title: Dialog +description: Open modal dialogs +--- + +# Dialog + +Open a modal dialog with custom content. + +## Protocol + +```typescript +{ + type: 'dialog', + title?: string, + width?: number | string, + body: Component, + footer?: Component[], + closable?: boolean, +} +``` + +## Examples + +### Form Dialog + +```json +{ + "type": "button", + "label": "Add User", + "onClick": { + "type": "dialog", + "title": "Create New User", + "width": 600, + "body": { + "type": "form", + "api": "/api/users", + "fields": [ + { "type": "input", "name": "name", "label": "Name", "required": true }, + { "type": "input", "name": "email", "label": "Email", "inputType": "email", "required": true } + ] + } + } +} +``` + +### Confirmation Dialog + +```json +{ + "type": "dialog", + "title": "Confirm Action", + "body": { + "type": "text", + "value": "Are you sure you want to proceed?" + }, + "footer": [ + { "type": "button", "label": "Cancel", "onClick": { "type": "close" } }, + { "type": "button", "label": "Confirm", "onClick": { "type": "api", "api": "/api/confirm" } } + ] +} +``` + +### Content Dialog + +```json +{ + "type": "button", + "label": "View Details", + "onClick": { + "type": "dialog", + "title": "User Details", + "width": "80%", + "body": { + "type": "card", + "body": [ + { "type": "text", "value": "Name: ${user.name}" }, + { "type": "text", "value": "Email: ${user.email}" }, + { "type": "text", "value": "Role: ${user.role}" } + ] + } + } +} +``` + +## Features + +### Width + +Control dialog width with: +- Fixed pixel values: `600` +- Percentage: `"80%"` +- Preset sizes: `"sm"`, `"md"`, `"lg"`, `"xl"` + +### Closable + +Set `closable: false` to prevent users from closing the dialog via the close button or ESC key. + +### Body Content + +The dialog body can contain any component: +- Forms for data entry +- Cards for content display +- Tables for data selection +- Custom component compositions + +### Footer + +Add custom footer buttons for actions like Cancel, Confirm, Save, etc. + +## Use Cases + +- Create/edit forms +- Confirmation prompts +- Detail views +- Multi-step wizards +- Image galleries + +## Related + +- **[Form](/docs/03-objectui/container-components/form)** - Forms in dialogs +- **[API Request](/docs/03-objectui/actions/api-request)** - Submit from dialog diff --git a/content/docs/cn/03-objectui/actions/index.mdx b/content/docs/cn/03-objectui/actions/index.mdx new file mode 100644 index 0000000..7581acb --- /dev/null +++ b/content/docs/cn/03-objectui/actions/index.mdx @@ -0,0 +1,103 @@ +--- +title: Actions +description: Interactive behaviors and event handlers in ObjectUI +--- + +# Actions + +Actions define interactive behaviors in ObjectUI. + +## Action Types + +- **[API Request](/docs/03-objectui/actions/api-request)** - Make HTTP requests +- **[Navigate](/docs/03-objectui/actions/navigate)** - Navigate to different pages +- **[Dialog](/docs/03-objectui/actions/dialog)** - Open modal dialogs +- **[Toast](/docs/03-objectui/actions/toast)** - Show notification messages + +## Overview + +Actions are the interactive layer of ObjectUI, handling user events and triggering responses. They support: + +- **Chaining**: Actions can trigger other actions (onSuccess, onError) +- **Template Substitution**: Use `${variable}` syntax for dynamic values +- **Confirmation**: Add confirm prompts before execution +- **Error Handling**: Built-in error handling and user feedback + +## Common Patterns + +### Form Submission + +```json +{ + "type": "form", + "fields": [...], + "onSubmit": { + "type": "api", + "api": "/api/users", + "method": "POST", + "onSuccess": { + "type": "toast", + "message": "User created successfully!" + } + } +} +``` + +### Button Actions + +```json +{ + "type": "button", + "label": "Save", + "onClick": { + "type": "api", + "api": "/api/save", + "method": "POST", + "data": "${formData}" + } +} +``` + +### Navigation + +```json +{ + "type": "button", + "label": "View Details", + "onClick": { + "type": "navigate", + "url": "/users/${userId}" + } +} +``` + +## Action Chaining + +Actions can trigger other actions on success or error: + +```json +{ + "type": "api", + "api": "/api/users/${id}", + "method": "DELETE", + "confirm": "Delete this user?", + "onSuccess": [ + { "type": "toast", "message": "User deleted" }, + { "type": "reload" } + ], + "onError": { + "type": "toast", + "message": "Failed to delete user", + "variant": "error" + } +} +``` + +## Next Steps + +Explore individual action types for detailed protocol definitions and examples: + +- **[API Request](/docs/03-objectui/actions/api-request)** - HTTP requests +- **[Navigate](/docs/03-objectui/actions/navigate)** - Page navigation +- **[Dialog](/docs/03-objectui/actions/dialog)** - Modal dialogs +- **[Toast](/docs/03-objectui/actions/toast)** - Notifications diff --git a/content/docs/cn/03-objectui/actions/meta.json b/content/docs/cn/03-objectui/actions/meta.json new file mode 100644 index 0000000..5305a5f --- /dev/null +++ b/content/docs/cn/03-objectui/actions/meta.json @@ -0,0 +1,10 @@ +{ + "title": "Actions", + "pages": [ + "index", + "api-request", + "navigate", + "dialog", + "toast" + ] +} diff --git a/content/docs/cn/03-objectui/actions/navigate.mdx b/content/docs/cn/03-objectui/actions/navigate.mdx new file mode 100644 index 0000000..a413a69 --- /dev/null +++ b/content/docs/cn/03-objectui/actions/navigate.mdx @@ -0,0 +1,105 @@ +--- +title: Navigate +description: Navigate to different pages +--- + +# Navigate + +Navigate to a different page or URL. + +## Protocol + +```typescript +{ + type: 'navigate', + url: string, // Target URL (template supported) + newTab?: boolean, // Open in new tab + replace?: boolean, // Replace current history entry +} +``` + +## Examples + +### Basic Navigation + +```json +{ + "type": "button", + "label": "View Details", + "onClick": { + "type": "navigate", + "url": "/users/${userId}" + } +} +``` + +### Open in New Tab + +```json +{ + "type": "button", + "label": "External Link", + "onClick": { + "type": "navigate", + "url": "https://example.com", + "newTab": true + } +} +``` + +### Replace History + +```json +{ + "type": "navigate", + "url": "/login", + "replace": true +} +``` + +### Navigate After API Call + +```json +{ + "type": "api", + "api": "/api/users", + "method": "POST", + "data": "${formData}", + "onSuccess": { + "type": "navigate", + "url": "/users/${response.id}" + } +} +``` + +## Features + +### Template URLs + +Use template variables in the URL: + +```json +{ + "url": "/users/${userId}/posts/${postId}" +} +``` + +### New Tab + +Open links in a new browser tab with `newTab: true`. + +### History Management + +Use `replace: true` to replace the current history entry instead of adding a new one. Useful for login redirects. + +## Use Cases + +- Navigate to detail pages +- Redirect after form submission +- Open external links +- Navigate back/forward in history + +## Related + +- **[API Request](/docs/03-objectui/actions/api-request)** - Navigate after API calls +- **[Page](/docs/03-objectui/container-components/page)** - Page component diff --git a/content/docs/cn/03-objectui/actions/toast.mdx b/content/docs/cn/03-objectui/actions/toast.mdx new file mode 100644 index 0000000..dc56764 --- /dev/null +++ b/content/docs/cn/03-objectui/actions/toast.mdx @@ -0,0 +1,130 @@ +--- +title: Toast +description: Show notification messages +--- + +# Toast + +Show notification messages to users. + +## Protocol + +```typescript +{ + type: 'toast', + message: string, // Message text (template supported) + variant?: 'success' | 'error' | 'warning' | 'info', + duration?: number, // Auto-close duration (ms) +} +``` + +## Examples + +### Success Message + +```json +{ + "type": "toast", + "message": "Operation completed successfully!", + "variant": "success", + "duration": 3000 +} +``` + +### Error Message + +```json +{ + "type": "toast", + "message": "Failed to save changes", + "variant": "error", + "duration": 5000 +} +``` + +### Warning Message + +```json +{ + "type": "toast", + "message": "Please review your changes before submitting", + "variant": "warning" +} +``` + +### Info Message + +```json +{ + "type": "toast", + "message": "Your session will expire in 5 minutes", + "variant": "info", + "duration": 10000 +} +``` + +### After API Call + +```json +{ + "type": "api", + "api": "/api/users", + "method": "POST", + "onSuccess": { + "type": "toast", + "message": "User created: ${response.name}", + "variant": "success" + }, + "onError": { + "type": "toast", + "message": "Error: ${error.message}", + "variant": "error" + } +} +``` + +## Variants + +Toast messages support four variants: + +- **success** - Green checkmark icon, positive feedback +- **error** - Red X icon, error messages +- **warning** - Yellow alert icon, warnings +- **info** - Blue info icon, informational messages + +## Duration + +Control how long the toast appears: + +- Default: `3000ms` (3 seconds) +- Set to `0` for persistent toasts (require manual dismissal) +- Longer for important messages: `5000-10000ms` + +## Template Variables + +Use template syntax for dynamic messages: + +```json +{ + "message": "Welcome back, ${user.name}!", + "variant": "success" +} +``` + +## Multiple Toasts + +Chain multiple toasts: + +```json +{ + "onSuccess": [ + { "type": "toast", "message": "Data saved", "variant": "success" }, + { "type": "toast", "message": "Email sent", "variant": "info" } + ] +} +``` + +## Related + +- **[API Request](/docs/03-objectui/actions/api-request)** - Show feedback after API calls +- **[Form](/docs/03-objectui/container-components/form)** - Form submission feedback diff --git a/content/docs/cn/03-objectui/basic-components/datepicker.mdx b/content/docs/cn/03-objectui/basic-components/datepicker.mdx new file mode 100644 index 0000000..99cbb22 --- /dev/null +++ b/content/docs/cn/03-objectui/basic-components/datepicker.mdx @@ -0,0 +1,117 @@ +--- +title: DatePicker +description: Date and time selection component +--- + +# DatePicker + +Date and time selection component. + +## Protocol + +```typescript +{ + type: 'datepicker', + name: string, + label?: string, + placeholder?: string, + defaultValue?: string | Date, + required?: boolean, + disabled?: boolean, + mode?: 'date' | 'datetime' | 'time' | 'daterange', + format?: string, // Display format (e.g., 'YYYY-MM-DD') + minDate?: string | Date, // Minimum selectable date + maxDate?: string | Date, // Maximum selectable date + disabledDates?: string[], // Array of disabled dates + showTime?: boolean, // Show time picker + onChange?: Action, +} +``` + +## Examples + +### Simple Date + +```json +{ + "type": "datepicker", + "name": "birthday", + "label": "Date of Birth", + "mode": "date", + "maxDate": "today", + "required": true +} +``` + +### DateTime + +```json +{ + "type": "datepicker", + "name": "appointment", + "label": "Appointment Time", + "mode": "datetime", + "format": "YYYY-MM-DD HH:mm", + "minDate": "today", + "showTime": true +} +``` + +### Date Range + +```json +{ + "type": "datepicker", + "name": "dateRange", + "label": "Select Period", + "mode": "daterange", + "defaultValue": { + "start": "2024-01-01", + "end": "2024-12-31" + } +} +``` + +### Time Only + +```json +{ + "type": "datepicker", + "name": "meetingTime", + "label": "Meeting Time", + "mode": "time", + "format": "HH:mm" +} +``` + +## Modes + +The DatePicker supports four modes: + +- **date** - Date selection only +- **datetime** - Date and time selection +- **time** - Time selection only +- **daterange** - Select a date range (start and end dates) + +## Date Constraints + +Control which dates users can select: + +- **minDate** - Earliest selectable date (use "today" for current date) +- **maxDate** - Latest selectable date +- **disabledDates** - Array of specific dates to disable + +## Format Strings + +Common format patterns: + +- `YYYY-MM-DD` - 2024-01-15 +- `YYYY/MM/DD` - 2024/01/15 +- `DD/MM/YYYY` - 15/01/2024 +- `YYYY-MM-DD HH:mm` - 2024-01-15 14:30 +- `HH:mm` - 14:30 + +## Related Components + +- **[Input](/docs/03-objectui/basic-components/input)** - For text entry +- **[Form](/docs/03-objectui/container-components/form)** - Form container diff --git a/content/docs/cn/03-objectui/basic-components/index.mdx b/content/docs/cn/03-objectui/basic-components/index.mdx new file mode 100644 index 0000000..bbce21a --- /dev/null +++ b/content/docs/cn/03-objectui/basic-components/index.mdx @@ -0,0 +1,49 @@ +--- +title: Basic Components +description: Fundamental form and input components in ObjectUI +--- + +# Basic Components + +Basic components are the fundamental building blocks for forms and data input. + +## Component List + +- **[Input](/docs/03-objectui/basic-components/input)** - Text input field for single-line text entry +- **[Select](/docs/03-objectui/basic-components/select)** - Dropdown selection field +- **[DatePicker](/docs/03-objectui/basic-components/datepicker)** - Date and time selection component +- **[Switch](/docs/03-objectui/basic-components/switch)** - Toggle switch for boolean values + +## Overview + +Basic components handle user data entry through various input types. They support: + +- **Validation**: Built-in validation rules and custom patterns +- **Event Handling**: onChange events for real-time interactions +- **API Integration**: Dynamic data loading and dependent fields +- **Accessibility**: Keyboard navigation and screen reader support + +## Common Properties + +All basic components share these common properties: + +```typescript +{ + name: string, // Field identifier + label?: string, // Display label + placeholder?: string, // Placeholder text + defaultValue?: any, // Initial value + required?: boolean, // Required validation + disabled?: boolean, // Disabled state + onChange?: Action, // Change event handler +} +``` + +## Next Steps + +Explore individual components for detailed protocol definitions and examples: + +- **[Input](/docs/03-objectui/basic-components/input)** - Single-line text entry +- **[Select](/docs/03-objectui/basic-components/select)** - Dropdown selection +- **[DatePicker](/docs/03-objectui/basic-components/datepicker)** - Date/time picker +- **[Switch](/docs/03-objectui/basic-components/switch)** - Boolean toggle diff --git a/content/docs/cn/03-objectui/basic-components/input.mdx b/content/docs/cn/03-objectui/basic-components/input.mdx new file mode 100644 index 0000000..a035aa8 --- /dev/null +++ b/content/docs/cn/03-objectui/basic-components/input.mdx @@ -0,0 +1,105 @@ +--- +title: Input +description: Text input field for single-line text entry +--- + +# Input + +Text input field for single-line text entry. + +## Protocol + +```typescript +{ + type: 'input', + name: string, // Field name + label?: string, // Display label + placeholder?: string, // Placeholder text + defaultValue?: string, // Default value + required?: boolean, // Required validation + disabled?: boolean, // Disabled state + maxLength?: number, // Maximum length + minLength?: number, // Minimum length + pattern?: string, // Regex pattern + inputType?: 'text' | 'email' | 'password' | 'url' | 'tel' | 'number', + onChange?: Action, // Change event handler +} +``` + +## Examples + +### Basic Input + +```json +{ + "type": "input", + "name": "email", + "label": "Email Address", + "placeholder": "user@example.com", + "inputType": "email", + "required": true, + "maxLength": 255 +} +``` + +### Password Input + +```json +{ + "type": "input", + "name": "password", + "label": "Password", + "inputType": "password", + "required": true, + "minLength": 8, + "pattern": "^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d).+$" +} +``` + +### Dependent Fields + +```json +{ + "type": "form", + "fields": [ + { + "type": "input", + "name": "username", + "label": "Username", + "required": true, + "onChange": { + "type": "api", + "api": "/api/check-username", + "method": "POST", + "data": { "username": "${value}" } + } + } + ] +} +``` + +## Input Types + +The `inputType` property supports the following values: + +- **text** (default) - Plain text input +- **email** - Email address with validation +- **password** - Masked password input +- **url** - URL with validation +- **tel** - Telephone number +- **number** - Numeric input with increment/decrement + +## Validation + +Input supports multiple validation options: + +- **required** - Field must have a value +- **maxLength** - Maximum character length +- **minLength** - Minimum character length +- **pattern** - Regular expression pattern for custom validation + +## Related Components + +- **[Select](/docs/03-objectui/basic-components/select)** - For predefined options +- **[DatePicker](/docs/03-objectui/basic-components/datepicker)** - For date/time input +- **[Form](/docs/03-objectui/container-components/form)** - Form container diff --git a/content/docs/cn/03-objectui/basic-components/meta.json b/content/docs/cn/03-objectui/basic-components/meta.json new file mode 100644 index 0000000..e3ebd2a --- /dev/null +++ b/content/docs/cn/03-objectui/basic-components/meta.json @@ -0,0 +1,10 @@ +{ + "title": "Basic Components", + "pages": [ + "index", + "input", + "select", + "datepicker", + "switch" + ] +} diff --git a/content/docs/cn/03-objectui/basic-components/select.mdx b/content/docs/cn/03-objectui/basic-components/select.mdx new file mode 100644 index 0000000..ff0fa77 --- /dev/null +++ b/content/docs/cn/03-objectui/basic-components/select.mdx @@ -0,0 +1,128 @@ +--- +title: Select +description: Dropdown selection field +--- + +# Select + +Dropdown selection field. + +## Protocol + +```typescript +{ + type: 'select', + name: string, + label?: string, + placeholder?: string, + defaultValue?: string | number, + required?: boolean, + disabled?: boolean, + multiple?: boolean, // Allow multiple selections + searchable?: boolean, // Enable search/filter + clearable?: boolean, // Show clear button + options?: Array<{ // Static options + label: string, + value: string | number, + disabled?: boolean + }>, + api?: string, // API endpoint for dynamic options + optionLabel?: string, // Field name for option label + optionValue?: string, // Field name for option value + dependsOn?: string, // Field dependency + onChange?: Action, +} +``` + +## Examples + +### Static Options + +```json +{ + "type": "select", + "name": "status", + "label": "Status", + "placeholder": "Select status", + "required": true, + "options": [ + { "label": "Active", "value": "active" }, + { "label": "Inactive", "value": "inactive" }, + { "label": "Pending", "value": "pending" } + ] +} +``` + +### Dynamic Options from API + +```json +{ + "type": "select", + "name": "category", + "label": "Category", + "api": "/api/categories", + "optionLabel": "name", + "optionValue": "id", + "searchable": true +} +``` + +### Dependent Select + +```json +{ + "type": "form", + "fields": [ + { + "type": "select", + "name": "country", + "label": "Country", + "api": "/api/countries" + }, + { + "type": "select", + "name": "state", + "label": "State", + "api": "/api/states?country=${country}", + "dependsOn": "country" + } + ] +} +``` + +### Multiple Selection + +```json +{ + "type": "select", + "name": "tags", + "label": "Tags", + "multiple": true, + "searchable": true, + "options": [ + { "label": "Important", "value": "important" }, + { "label": "Urgent", "value": "urgent" }, + { "label": "Review", "value": "review" } + ] +} +``` + +## Features + +### Static vs Dynamic Options + +- **Static options** - Use the `options` array for predefined choices +- **Dynamic options** - Use `api` to fetch options from a backend endpoint + +### Search and Filter + +Enable `searchable: true` to allow users to filter options by typing. + +### Dependent Fields + +Use `dependsOn` to create cascading selects where one field's options depend on another field's value. + +## Related Components + +- **[Input](/docs/03-objectui/basic-components/input)** - For text entry +- **[Form](/docs/03-objectui/container-components/form)** - Form container diff --git a/content/docs/cn/03-objectui/basic-components/switch.mdx b/content/docs/cn/03-objectui/basic-components/switch.mdx new file mode 100644 index 0000000..c1e8327 --- /dev/null +++ b/content/docs/cn/03-objectui/basic-components/switch.mdx @@ -0,0 +1,101 @@ +--- +title: Switch +description: Toggle switch for boolean values +--- + +# Switch + +Toggle switch for boolean values. + +## Protocol + +```typescript +{ + type: 'switch', + name: string, + label?: string, + defaultValue?: boolean, + disabled?: boolean, + checkedText?: string, // Text when checked + uncheckedText?: string, // Text when unchecked + onChange?: Action, +} +``` + +## Examples + +### Basic Switch + +```json +{ + "type": "switch", + "name": "isActive", + "label": "Active Status", + "defaultValue": true, + "checkedText": "Active", + "uncheckedText": "Inactive" +} +``` + +### Simple Toggle + +```json +{ + "type": "switch", + "name": "notifications", + "label": "Enable Notifications", + "defaultValue": false +} +``` + +### With Change Handler + +```json +{ + "type": "switch", + "name": "autoSave", + "label": "Auto-Save", + "defaultValue": true, + "onChange": { + "type": "api", + "api": "/api/settings/auto-save", + "method": "POST", + "data": { "enabled": "${value}" } + } +} +``` + +## Features + +### State Labels + +Use `checkedText` and `uncheckedText` to provide visual feedback about the current state: + +```json +{ + "type": "switch", + "name": "visibility", + "label": "Post Visibility", + "checkedText": "Public", + "uncheckedText": "Private" +} +``` + +### Default State + +Set `defaultValue: true` to make the switch checked by default, or `false` for unchecked. + +## Use Cases + +Switches are ideal for: + +- Enabling/disabling features +- Toggling visibility +- Activating/deactivating settings +- Binary choices (yes/no, on/off) + +## Related Components + +- **[Input](/docs/03-objectui/basic-components/input)** - For text entry +- **[Select](/docs/03-objectui/basic-components/select)** - For multiple options +- **[Form](/docs/03-objectui/container-components/form)** - Form container diff --git a/content/docs/cn/03-objectui/component-spec.mdx b/content/docs/cn/03-objectui/component-spec.mdx index 627934f..04aa46f 100644 --- a/content/docs/cn/03-objectui/component-spec.mdx +++ b/content/docs/cn/03-objectui/component-spec.mdx @@ -5,783 +5,88 @@ description: 所有 ObjectUI 组件的完整协议参考 # 组件规范 -这份全面的参考文档记录了所有 ObjectUI 组件及其 JSON 协议。 +这份全面的参考文档记录了所有 ObjectUI 组件及其 JSON 协议。规范按三个主要类别组织,便于导航。 -## 基础组件 +## 概述 -基础组件是表单和数据输入的基本构建块。 +ObjectUI 使用基于 JSON 的协议来声明式地定义用户界面。每个组件都有特定的类型和一组控制其外观和行为的属性。 -### Input 输入框 +## 组件分类 -单行文本输入字段。 +### 基础组件 -**协议:** +处理用户数据输入的表单和输入组件。 -```typescript -{ - type: 'input', - name: string, // 字段名 - label?: string, // 显示标签 - placeholder?: string, // 占位符文本 - defaultValue?: string, // 默认值 - required?: boolean, // 必填验证 - disabled?: boolean, // 禁用状态 - maxLength?: number, // 最大长度 - minLength?: number, // 最小长度 - pattern?: string, // 正则表达式 - inputType?: 'text' | 'email' | 'password' | 'url' | 'tel' | 'number', - onChange?: Action, // 变化事件处理器 -} -``` - -**示例:** - -```json -{ - "type": "input", - "name": "email", - "label": "邮箱地址", - "placeholder": "user@example.com", - "inputType": "email", - "required": true, - "maxLength": 255 -} -``` - -**高级示例 - 依赖字段:** - -```json -{ - "type": "form", - "fields": [ - { - "type": "input", - "name": "username", - "label": "用户名", - "required": true, - "onChange": { - "type": "api", - "api": "/api/check-username", - "method": "POST", - "data": { "username": "${value}" } - } - } - ] -} -``` - -### Select 下拉选择 - -下拉选择字段。 - -**协议:** - -```typescript -{ - type: 'select', - name: string, - label?: string, - placeholder?: string, - defaultValue?: string | number, - required?: boolean, - disabled?: boolean, - multiple?: boolean, // 允许多选 - searchable?: boolean, // 启用搜索/过滤 - clearable?: boolean, // 显示清除按钮 - options?: Array<{ // 静态选项 - label: string, - value: string | number, - disabled?: boolean - }>, - api?: string, // 动态选项的 API 端点 - optionLabel?: string, // 选项标签的字段名 - optionValue?: string, // 选项值的字段名 - dependsOn?: string, // 字段依赖 - onChange?: Action, -} -``` - -**示例 - 静态选项:** - -```json -{ - "type": "select", - "name": "status", - "label": "状态", - "placeholder": "选择状态", - "required": true, - "options": [ - { "label": "激活", "value": "active" }, - { "label": "未激活", "value": "inactive" }, - { "label": "待审核", "value": "pending" } - ] -} -``` +**包括:** Input 输入框、Select 下拉选择、DatePicker 日期选择器、Switch 开关 -**示例 - 从 API 获取动态选项:** +→ **[查看基础组件](/docs/03-objectui/basic-components)** -```json -{ - "type": "select", - "name": "category", - "label": "分类", - "api": "/api/categories", - "optionLabel": "name", - "optionValue": "id", - "searchable": true -} -``` +### 容器组件 -**示例 - 级联选择:** +组织 UI 的布局和结构组件。 -```json -{ - "type": "form", - "fields": [ - { - "type": "select", - "name": "country", - "label": "国家", - "api": "/api/countries" - }, - { - "type": "select", - "name": "state", - "label": "省/州", - "api": "/api/states?country=${country}", - "dependsOn": "country" - } - ] -} -``` +**包括:** Page 页面、Grid 网格、Card 卡片、Form 表单、Table 表格 -### DatePicker 日期选择器 +→ **[查看容器组件](/docs/03-objectui/container-components)** -日期和时间选择组件。 +### 操作(Actions) -**协议:** +交互行为和事件处理器。 -```typescript -{ - type: 'datepicker', - name: string, - label?: string, - placeholder?: string, - defaultValue?: string | Date, - required?: boolean, - disabled?: boolean, - mode?: 'date' | 'datetime' | 'time' | 'daterange', - format?: string, // 显示格式 (例如 'YYYY-MM-DD') - minDate?: string | Date, // 最小可选日期 - maxDate?: string | Date, // 最大可选日期 - disabledDates?: string[], // 禁用日期数组 - showTime?: boolean, // 显示时间选择器 - onChange?: Action, -} -``` +**包括:** API 请求、导航、对话框、提示消息 -**示例 - 简单日期:** +→ **[查看操作](/docs/03-objectui/actions)** -```json -{ - "type": "datepicker", - "name": "birthday", - "label": "出生日期", - "mode": "date", - "maxDate": "today", - "required": true -} -``` - -**示例 - 日期时间:** - -```json -{ - "type": "datepicker", - "name": "appointment", - "label": "预约时间", - "mode": "datetime", - "format": "YYYY-MM-DD HH:mm", - "minDate": "today", - "showTime": true -} -``` +## 快速示例 -**示例 - 日期范围:** - -```json -{ - "type": "datepicker", - "name": "dateRange", - "label": "选择时间段", - "mode": "daterange", - "defaultValue": { - "start": "2024-01-01", - "end": "2024-12-31" - } -} -``` - -### Switch 开关 - -布尔值的切换开关。 - -**协议:** - -```typescript -{ - type: 'switch', - name: string, - label?: string, - defaultValue?: boolean, - disabled?: boolean, - checkedText?: string, // 选中时的文本 - uncheckedText?: string, // 未选中时的文本 - onChange?: Action, -} -``` - -**示例:** - -```json -{ - "type": "switch", - "name": "isActive", - "label": "激活状态", - "defaultValue": true, - "checkedText": "已激活", - "uncheckedText": "未激活" -} -``` - -## 容器组件 - -容器组件用于组织和构建 UI 布局。 - -### Page 页面 - -顶级页面容器,带有标题和操作。 - -**协议:** - -```typescript -{ - type: 'page', - title: string, - description?: string, - icon?: string, - breadcrumbs?: Array<{ - label: string, - url?: string - }>, - actions?: Action[], // 页头操作 - tabs?: Array<{ - label: string, - key: string, - body: Component - }>, - body: Component | Component[], -} -``` - -**示例:** +以下是结合不同组件类型的简单示例: ```json { "type": "page", - "title": "用户管理", - "description": "管理系统用户和权限", - "breadcrumbs": [ - { "label": "首页", "url": "/" }, - { "label": "用户" } - ], - "actions": [ - { - "label": "添加用户", - "type": "dialog", - "body": { - "type": "form", - "api": "/api/users", - "fields": [...] - } - } - ], - "body": { - "type": "table", - "api": "/api/users" - } -} -``` - -### Grid 网格 - -响应式网格布局。 - -**协议:** - -```typescript -{ - type: 'grid', - columns?: number | { // 列配置 - xs?: number, // 超小设备 - sm?: number, // 小设备 - md?: number, // 中等设备 - lg?: number, // 大设备 - xl?: number // 超大设备 - }, - gap?: number | string, // 项目间距 - items: Component[], -} -``` - -**示例:** - -```json -{ - "type": "grid", - "columns": { "xs": 1, "sm": 2, "lg": 3 }, - "gap": "20px", - "items": [ - { - "type": "card", - "title": "总用户数", - "body": { "type": "text", "value": "${stats.users}" } - }, - { - "type": "card", - "title": "总订单数", - "body": { "type": "text", "value": "${stats.orders}" } - }, - { - "type": "card", - "title": "收入", - "body": { "type": "text", "value": "¥${stats.revenue}" } - } - ] -} -``` - -### Card 卡片 - -带有标题、主体和页脚的卡片容器。 - -**协议:** - -```typescript -{ - type: 'card', - title?: string, - description?: string, - cover?: string, // 封面图片 URL - avatar?: string, // 头像图片 URL - actions?: Action[], - body: Component | Component[], - footer?: Component | Component[], -} -``` - -**示例:** - -```json -{ - "type": "card", "title": "用户资料", - "avatar": "${user.avatar}", - "body": [ - { "type": "text", "value": "姓名: ${user.name}" }, - { "type": "text", "value": "邮箱: ${user.email}" }, - { "type": "text", "value": "角色: ${user.role}" } - ], - "actions": [ - { "label": "编辑", "onClick": { "type": "navigate", "url": "/users/${user.id}/edit" } }, - { "label": "删除", "onClick": { "type": "api", "api": "/api/users/${user.id}", "method": "DELETE" } } - ] -} -``` - -### Form 表单 - -带有字段和提交处理的表单容器。 - -**协议:** - -```typescript -{ - type: 'form', - title?: string, - api?: string, // 提交端点 - method?: 'POST' | 'PUT' | 'PATCH', - initialValues?: object, // 初始表单值 - fields: FormField[], - layout?: 'horizontal' | 'vertical' | 'inline', - columns?: number, // 多列布局 - submitText?: string, // 提交按钮文本 - resetText?: string, // 重置按钮文本 - showReset?: boolean, // 显示重置按钮 - onSubmit?: Action, - onSuccess?: Action, - onError?: Action, -} -``` - -**示例 - 简单表单:** - -```json -{ - "type": "form", - "title": "创建用户", - "api": "/api/users", - "method": "POST", - "fields": [ - { - "type": "input", - "name": "name", - "label": "全名", - "required": true - }, - { - "type": "input", - "name": "email", - "label": "邮箱", - "inputType": "email", - "required": true - }, - { - "type": "select", - "name": "role", - "label": "角色", - "options": [ - { "label": "管理员", "value": "admin" }, - { "label": "用户", "value": "user" } - ] - } - ], - "submitText": "创建用户", - "onSuccess": { - "type": "toast", - "message": "用户创建成功!" - } -} -``` - -**示例 - 多列表单:** - -```json -{ - "type": "form", - "title": "用户注册", - "columns": 2, - "fields": [ - { "type": "input", "name": "firstName", "label": "名" }, - { "type": "input", "name": "lastName", "label": "姓" }, - { "type": "input", "name": "email", "label": "邮箱", "inputType": "email" }, - { "type": "input", "name": "phone", "label": "电话", "inputType": "tel" }, - { "type": "datepicker", "name": "birthday", "label": "生日" }, - { "type": "select", "name": "country", "label": "国家", "api": "/api/countries" } - ] -} -``` - -### Table 表格 - -带有排序、筛选和分页的数据表格。 - -**协议:** - -```typescript -{ - type: 'table', - api?: string, // 数据端点 - data?: any[], // 静态数据 - columns: Array<{ - name: string, - label: string, - type?: 'text' | 'number' | 'boolean' | 'date' | 'image', - sortable?: boolean, - filterable?: boolean, - width?: number | string, - render?: string, // 自定义渲染模板 - }>, - rowActions?: Action[], // 每行操作 - batchActions?: Action[], // 批量操作 - pagination?: boolean, - pageSize?: number, - searchable?: boolean, // 全局搜索 - filters?: Array<{ - name: string, - label: string, - type: 'input' | 'select' | 'datepicker' - }>, - selectable?: boolean, // 行选择 - expandable?: Component, // 可展开行内容 -} -``` - -**示例 - 基础表格:** - -```json -{ - "type": "table", - "api": "/api/users", - "columns": [ - { "name": "id", "label": "ID", "width": 80 }, - { "name": "name", "label": "姓名", "sortable": true }, - { "name": "email", "label": "邮箱", "sortable": true }, - { "name": "role", "label": "角色", "filterable": true }, - { "name": "createdAt", "label": "创建时间", "type": "date", "sortable": true } - ], - "rowActions": [ - { "label": "编辑", "onClick": { "type": "navigate", "url": "/users/${id}/edit" } }, - { "label": "删除", "onClick": { "type": "api", "api": "/api/users/${id}", "method": "DELETE", "confirm": "删除此用户?" } } - ], - "pagination": true, - "pageSize": 20, - "searchable": true -} -``` - -**示例 - CRUD 表格:** - -```json -{ - "type": "table", - "api": "/api/products", - "columns": [ - { "name": "name", "label": "产品名称" }, - { "name": "price", "label": "价格", "type": "number" }, - { "name": "stock", "label": "库存", "type": "number" }, - { "name": "active", "label": "激活", "type": "boolean" } - ], - "filters": [ - { "name": "category", "label": "分类", "type": "select", "api": "/api/categories" }, - { "name": "priceRange", "label": "价格区间", "type": "input" } - ], - "selectable": true, - "batchActions": [ - { "label": "批量删除", "onClick": { "type": "api", "api": "/api/products/batch-delete", "method": "POST" } }, - { "label": "导出", "onClick": { "type": "download", "url": "/api/products/export" } } - ], - "rowActions": [ - { "label": "编辑", "onClick": { "type": "dialog", "title": "编辑产品", "body": { "type": "form", "fields": [...] } } }, - { "label": "删除", "onClick": { "type": "api", "api": "/api/products/${id}", "method": "DELETE" } } - ] -} -``` - -## 操作(Actions) - -操作定义 ObjectUI 中的交互行为。 - -### API 请求 - -发起 HTTP 请求。 - -**协议:** - -```typescript -{ - type: 'api', - api: string, // API 端点 - method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE', - data?: object | string, // 请求体 (支持模板) - headers?: object, // 请求头 - confirm?: string, // 确认消息 - onSuccess?: Action, // 成功处理器 - onError?: Action, // 错误处理器 -} -``` - -**示例:** - -```json -{ - "type": "button", - "label": "保存", - "onClick": { - "type": "api", - "api": "/api/users/${userId}", - "method": "PUT", - "data": "${formData}", - "confirm": "保存更改?", - "onSuccess": { - "type": "toast", - "message": "保存成功!" - } - } -} -``` - -### 导航 - -导航到不同页面。 - -**协议:** - -```typescript -{ - type: 'navigate', - url: string, // 目标 URL (支持模板) - newTab?: boolean, // 在新标签页打开 - replace?: boolean, // 替换当前历史记录 -} -``` - -**示例:** - -```json -{ - "type": "button", - "label": "查看详情", - "onClick": { - "type": "navigate", - "url": "/users/${userId}" - } -} -``` - -### 对话框 - -打开模态对话框。 - -**协议:** - -```typescript -{ - type: 'dialog', - title?: string, - width?: number | string, - body: Component, - footer?: Component[], - closable?: boolean, -} -``` - -**示例:** - -```json -{ - "type": "button", - "label": "添加用户", - "onClick": { - "type": "dialog", - "title": "创建新用户", - "width": 600, - "body": { - "type": "form", - "api": "/api/users", - "fields": [...] - } - } -} -``` - -### 提示消息 - -显示通知消息。 - -**协议:** - -```typescript -{ - type: 'toast', - message: string, // 消息文本 (支持模板) - variant?: 'success' | 'error' | 'warning' | 'info', - duration?: number, // 自动关闭时长 (毫秒) -} -``` - -**示例:** - -```json -{ - "type": "toast", - "message": "操作成功完成!", - "variant": "success", - "duration": 3000 -} -``` - -## 完整示例 - -### 用户管理 CRUD - -```json -{ - "type": "page", - "title": "用户管理", - "actions": [ - { - "label": "添加用户", - "onClick": { - "type": "dialog", - "title": "创建用户", - "body": { - "type": "form", - "api": "/api/users", - "method": "POST", - "fields": [ - { "type": "input", "name": "name", "label": "姓名", "required": true }, - { "type": "input", "name": "email", "label": "邮箱", "inputType": "email", "required": true }, - { "type": "select", "name": "role", "label": "角色", "options": [ - { "label": "管理员", "value": "admin" }, - { "label": "用户", "value": "user" } - ]} - ], - "onSuccess": [ - { "type": "toast", "message": "用户已创建!" }, - { "type": "reload" } - ] - } - } - } - ], "body": { - "type": "table", + "type": "form", "api": "/api/users", - "columns": [ - { "name": "name", "label": "姓名", "sortable": true }, - { "name": "email", "label": "邮箱" }, - { "name": "role", "label": "角色" }, - { "name": "createdAt", "label": "创建时间", "type": "date" } - ], - "rowActions": [ + "fields": [ { - "label": "编辑", - "onClick": { - "type": "dialog", - "title": "编辑用户", - "body": { - "type": "form", - "api": "/api/users/${id}", - "method": "PUT", - "initialValues": "${row}", - "fields": [ - { "type": "input", "name": "name", "label": "姓名" }, - { "type": "input", "name": "email", "label": "邮箱" } - ] - } - } + "type": "input", + "name": "name", + "label": "全名", + "required": true }, { - "label": "删除", - "onClick": { - "type": "api", - "api": "/api/users/${id}", - "method": "DELETE", - "confirm": "删除此用户?", - "onSuccess": [ - { "type": "toast", "message": "用户已删除" }, - { "type": "reload" } - ] - } + "type": "select", + "name": "role", + "label": "角色", + "options": [ + { "label": "管理员", "value": "admin" }, + { "label": "用户", "value": "user" } + ] } ], - "searchable": true, - "pagination": true + "onSuccess": { + "type": "toast", + "message": "资料已更新!" + } } } ``` +## 组件特性 + +所有 ObjectUI 组件支持: + +- **协议驱动**: 纯 JSON 配置 +- **类型安全**: 提供 TypeScript 定义 +- **模板支持**: 使用 `${variable}` 语法的动态值 +- **事件处理**: 灵活的操作系统 +- **验证**: 内置表单验证 +- **API 集成**: 原生支持 REST API + ## 下一步 +- **[基础组件](/docs/03-objectui/basic-components)** - 了解表单和输入组件 +- **[容器组件](/docs/03-objectui/container-components)** - 探索布局组件 +- **[操作](/docs/03-objectui/actions)** - 了解交互行为 - **[渲染器使用](/docs/03-objectui/renderer-usage)** - 了解如何在应用中集成这些组件 diff --git a/content/docs/cn/03-objectui/container-components/card.mdx b/content/docs/cn/03-objectui/container-components/card.mdx new file mode 100644 index 0000000..c99ae96 --- /dev/null +++ b/content/docs/cn/03-objectui/container-components/card.mdx @@ -0,0 +1,111 @@ +--- +title: Card +description: Card container with header, body, and footer +--- + +# Card + +Card container with header, body, and footer. + +## Protocol + +```typescript +{ + type: 'card', + title?: string, + description?: string, + cover?: string, // Cover image URL + avatar?: string, // Avatar image URL + actions?: Action[], + body: Component | Component[], + footer?: Component | Component[], +} +``` + +## Examples + +### Basic Card + +```json +{ + "type": "card", + "title": "User Profile", + "avatar": "${user.avatar}", + "body": [ + { "type": "text", "value": "Name: ${user.name}" }, + { "type": "text", "value": "Email: ${user.email}" }, + { "type": "text", "value": "Role: ${user.role}" } + ], + "actions": [ + { "label": "Edit", "onClick": { "type": "navigate", "url": "/users/${user.id}/edit" } }, + { "label": "Delete", "onClick": { "type": "api", "api": "/api/users/${user.id}", "method": "DELETE" } } + ] +} +``` + +### Card with Cover Image + +```json +{ + "type": "card", + "title": "Product", + "description": "Premium wireless headphones", + "cover": "/images/product.jpg", + "body": { + "type": "text", + "value": "$299.99" + }, + "actions": [ + { "label": "Buy Now", "onClick": {...} } + ] +} +``` + +### Stats Card + +```json +{ + "type": "card", + "title": "Total Sales", + "body": { + "type": "text", + "value": "$${stats.totalSales}", + "style": "text-3xl font-bold" + }, + "footer": { + "type": "text", + "value": "↑ 12% from last month" + } +} +``` + +## Features + +### Header + +Cards can have a title, description, and avatar/cover image in the header. + +### Body + +The body can contain any component or array of components. + +### Footer + +Optional footer for additional content or metadata. + +### Actions + +Action buttons appear in the card's action area. + +## Use Cases + +- User profiles +- Product listings +- Statistics/metrics +- Content previews +- Settings panels + +## Related Components + +- **[Grid](/docs/03-objectui/container-components/grid)** - Card layouts +- **[Page](/docs/03-objectui/container-components/page)** - Page container diff --git a/content/docs/cn/03-objectui/container-components/form.mdx b/content/docs/cn/03-objectui/container-components/form.mdx new file mode 100644 index 0000000..80e7a9b --- /dev/null +++ b/content/docs/cn/03-objectui/container-components/form.mdx @@ -0,0 +1,143 @@ +--- +title: Form +description: Form container with fields and submission handling +--- + +# Form + +Form container with fields and submission handling. + +## Protocol + +```typescript +{ + type: 'form', + title?: string, + api?: string, // Submit endpoint + method?: 'POST' | 'PUT' | 'PATCH', + initialValues?: object, // Initial form values + fields: FormField[], + layout?: 'horizontal' | 'vertical' | 'inline', + columns?: number, // Multi-column layout + submitText?: string, // Submit button text + resetText?: string, // Reset button text + showReset?: boolean, // Show reset button + onSubmit?: Action, + onSuccess?: Action, + onError?: Action, +} +``` + +## Examples + +### Simple Form + +```json +{ + "type": "form", + "title": "Create User", + "api": "/api/users", + "method": "POST", + "fields": [ + { + "type": "input", + "name": "name", + "label": "Full Name", + "required": true + }, + { + "type": "input", + "name": "email", + "label": "Email", + "inputType": "email", + "required": true + }, + { + "type": "select", + "name": "role", + "label": "Role", + "options": [ + { "label": "Admin", "value": "admin" }, + { "label": "User", "value": "user" } + ] + } + ], + "submitText": "Create User", + "onSuccess": { + "type": "toast", + "message": "User created successfully!" + } +} +``` + +### Multi-column Form + +```json +{ + "type": "form", + "title": "User Registration", + "columns": 2, + "fields": [ + { "type": "input", "name": "firstName", "label": "First Name" }, + { "type": "input", "name": "lastName", "label": "Last Name" }, + { "type": "input", "name": "email", "label": "Email", "inputType": "email" }, + { "type": "input", "name": "phone", "label": "Phone", "inputType": "tel" }, + { "type": "datepicker", "name": "birthday", "label": "Birthday" }, + { "type": "select", "name": "country", "label": "Country", "api": "/api/countries" } + ] +} +``` + +### Edit Form with Initial Values + +```json +{ + "type": "form", + "title": "Edit User", + "api": "/api/users/${userId}", + "method": "PUT", + "initialValues": { + "name": "John Doe", + "email": "john@example.com", + "role": "admin" + }, + "fields": [...] +} +``` + +## Features + +### Layouts + +Forms support three layout modes: + +- **vertical** (default) - Labels above fields +- **horizontal** - Labels beside fields +- **inline** - Fields in a single row + +### Multi-column + +Use `columns` to create multi-column layouts for better space utilization. + +### Validation + +Forms automatically validate fields based on their `required`, `pattern`, `minLength`, and `maxLength` properties. + +### Submission + +Forms can submit to an API endpoint or trigger custom actions via `onSubmit`. + +## Field Types + +Forms can contain any basic component: + +- [Input](/docs/03-objectui/basic-components/input) +- [Select](/docs/03-objectui/basic-components/select) +- [DatePicker](/docs/03-objectui/basic-components/datepicker) +- [Switch](/docs/03-objectui/basic-components/switch) + +## Related Components + +- **[Input](/docs/03-objectui/basic-components/input)** - Text input +- **[Select](/docs/03-objectui/basic-components/select)** - Dropdown +- **[Page](/docs/03-objectui/container-components/page)** - Page container diff --git a/content/docs/cn/03-objectui/container-components/grid.mdx b/content/docs/cn/03-objectui/container-components/grid.mdx new file mode 100644 index 0000000..6dbfac3 --- /dev/null +++ b/content/docs/cn/03-objectui/container-components/grid.mdx @@ -0,0 +1,108 @@ +--- +title: Grid +description: Responsive grid layout +--- + +# Grid + +Responsive grid layout. + +## Protocol + +```typescript +{ + type: 'grid', + columns?: number | { // Column configuration + xs?: number, // Extra small devices + sm?: number, // Small devices + md?: number, // Medium devices + lg?: number, // Large devices + xl?: number // Extra large devices + }, + gap?: number | string, // Gap between items + items: Component[], +} +``` + +## Examples + +### Responsive Grid + +```json +{ + "type": "grid", + "columns": { "xs": 1, "sm": 2, "lg": 3 }, + "gap": "20px", + "items": [ + { + "type": "card", + "title": "Total Users", + "body": { "type": "text", "value": "${stats.users}" } + }, + { + "type": "card", + "title": "Total Orders", + "body": { "type": "text", "value": "${stats.orders}" } + }, + { + "type": "card", + "title": "Revenue", + "body": { "type": "text", "value": "$${stats.revenue}" } + } + ] +} +``` + +### Fixed Columns + +```json +{ + "type": "grid", + "columns": 4, + "gap": "16px", + "items": [...] +} +``` + +## Responsive Breakpoints + +The grid supports five breakpoint sizes: + +- **xs** - Extra small (<576px) - Mobile portrait +- **sm** - Small (≥576px) - Mobile landscape +- **md** - Medium (≥768px) - Tablet +- **lg** - Large (≥992px) - Desktop +- **xl** - Extra large (≥1200px) - Large desktop + +## Layout Patterns + +### Dashboard Cards + +```json +{ + "type": "grid", + "columns": { "xs": 1, "md": 2, "xl": 4 }, + "items": [ + { "type": "card", "title": "Metric 1", "body": {...} }, + { "type": "card", "title": "Metric 2", "body": {...} }, + { "type": "card", "title": "Metric 3", "body": {...} }, + { "type": "card", "title": "Metric 4", "body": {...} } + ] +} +``` + +### Product Gallery + +```json +{ + "type": "grid", + "columns": { "xs": 2, "sm": 3, "lg": 4 }, + "gap": "24px", + "items": [...] +} +``` + +## Related Components + +- **[Card](/docs/03-objectui/container-components/card)** - Grid items +- **[Page](/docs/03-objectui/container-components/page)** - Page container diff --git a/content/docs/cn/03-objectui/container-components/index.mdx b/content/docs/cn/03-objectui/container-components/index.mdx new file mode 100644 index 0000000..6b43be3 --- /dev/null +++ b/content/docs/cn/03-objectui/container-components/index.mdx @@ -0,0 +1,74 @@ +--- +title: Container Components +description: Layout and structural components in ObjectUI +--- + +# Container Components + +Container components organize and structure the UI layout. + +## Component List + +- **[Page](/docs/03-objectui/container-components/page)** - Top-level page container +- **[Grid](/docs/03-objectui/container-components/grid)** - Responsive grid layout +- **[Card](/docs/03-objectui/container-components/card)** - Card container with header, body, and footer +- **[Form](/docs/03-objectui/container-components/form)** - Form container with fields and submission +- **[Table](/docs/03-objectui/container-components/table)** - Data table with sorting, filtering, and pagination + +## Overview + +Container components provide structure and layout capabilities for building complex UIs. They support: + +- **Nested Composition**: Components can contain other components +- **Responsive Design**: Automatic adaptation to different screen sizes +- **Data Binding**: Dynamic content from APIs or state +- **Action Handlers**: Built-in support for user interactions + +## Common Patterns + +### Page Layout + +Pages typically contain a header with actions and a body with content: + +```json +{ + "type": "page", + "title": "Dashboard", + "actions": [...], + "body": {...} +} +``` + +### Grid Layouts + +Use grids for responsive multi-column layouts: + +```json +{ + "type": "grid", + "columns": { "xs": 1, "sm": 2, "lg": 3 }, + "items": [...] +} +``` + +### Forms + +Forms group input fields with submission handling: + +```json +{ + "type": "form", + "fields": [...], + "onSubmit": {...} +} +``` + +## Next Steps + +Explore individual components for detailed protocol definitions and examples: + +- **[Page](/docs/03-objectui/container-components/page)** - Page container +- **[Grid](/docs/03-objectui/container-components/grid)** - Grid layout +- **[Card](/docs/03-objectui/container-components/card)** - Card component +- **[Form](/docs/03-objectui/container-components/form)** - Form container +- **[Table](/docs/03-objectui/container-components/table)** - Data table diff --git a/content/docs/cn/03-objectui/container-components/meta.json b/content/docs/cn/03-objectui/container-components/meta.json new file mode 100644 index 0000000..52b22ef --- /dev/null +++ b/content/docs/cn/03-objectui/container-components/meta.json @@ -0,0 +1,11 @@ +{ + "title": "Container Components", + "pages": [ + "index", + "page", + "grid", + "card", + "form", + "table" + ] +} diff --git a/content/docs/cn/03-objectui/container-components/page.mdx b/content/docs/cn/03-objectui/container-components/page.mdx new file mode 100644 index 0000000..361afb7 --- /dev/null +++ b/content/docs/cn/03-objectui/container-components/page.mdx @@ -0,0 +1,131 @@ +--- +title: Page +description: Top-level page container with header and actions +--- + +# Page + +Top-level page container with header and actions. + +## Protocol + +```typescript +{ + type: 'page', + title: string, + description?: string, + icon?: string, + breadcrumbs?: Array<{ + label: string, + url?: string + }>, + actions?: Action[], // Header actions + tabs?: Array<{ + label: string, + key: string, + body: Component + }>, + body: Component | Component[], +} +``` + +## Examples + +### Basic Page + +```json +{ + "type": "page", + "title": "User Management", + "description": "Manage system users and permissions", + "breadcrumbs": [ + { "label": "Home", "url": "/" }, + { "label": "Users" } + ], + "actions": [ + { + "label": "Add User", + "type": "dialog", + "body": { + "type": "form", + "api": "/api/users", + "fields": [...] + } + } + ], + "body": { + "type": "table", + "api": "/api/users" + } +} +``` + +### Page with Tabs + +```json +{ + "type": "page", + "title": "Settings", + "tabs": [ + { + "label": "General", + "key": "general", + "body": { "type": "form", "fields": [...] } + }, + { + "label": "Security", + "key": "security", + "body": { "type": "form", "fields": [...] } + } + ] +} +``` + +## Features + +### Breadcrumbs + +Breadcrumbs provide navigation context: + +```json +{ + "breadcrumbs": [ + { "label": "Home", "url": "/" }, + { "label": "Products", "url": "/products" }, + { "label": "Edit Product" } + ] +} +``` + +### Header Actions + +Actions appear in the page header: + +```json +{ + "actions": [ + { "label": "New", "onClick": {...} }, + { "label": "Import", "onClick": {...} }, + { "label": "Export", "onClick": {...} } + ] +} +``` + +### Tabs + +Organize content into tabbed sections: + +```json +{ + "tabs": [ + { "label": "Overview", "key": "overview", "body": {...} }, + { "label": "Details", "key": "details", "body": {...} } + ] +} +``` + +## Related Components + +- **[Table](/docs/03-objectui/container-components/table)** - Data display +- **[Form](/docs/03-objectui/container-components/form)** - Data entry +- **[Grid](/docs/03-objectui/container-components/grid)** - Layout diff --git a/content/docs/cn/03-objectui/container-components/table.mdx b/content/docs/cn/03-objectui/container-components/table.mdx new file mode 100644 index 0000000..58560e6 --- /dev/null +++ b/content/docs/cn/03-objectui/container-components/table.mdx @@ -0,0 +1,157 @@ +--- +title: Table +description: Data table with sorting, filtering, and pagination +--- + +# Table + +Data table with sorting, filtering, and pagination. + +## Protocol + +```typescript +{ + type: 'table', + api?: string, // Data endpoint + data?: any[], // Static data + columns: Array<{ + name: string, + label: string, + type?: 'text' | 'number' | 'boolean' | 'date' | 'image', + sortable?: boolean, + filterable?: boolean, + width?: number | string, + render?: string, // Custom render template + }>, + rowActions?: Action[], // Actions per row + batchActions?: Action[], // Batch actions + pagination?: boolean, + pageSize?: number, + searchable?: boolean, // Global search + filters?: Array<{ + name: string, + label: string, + type: 'input' | 'select' | 'datepicker' + }>, + selectable?: boolean, // Row selection + expandable?: Component, // Expandable row content +} +``` + +## Examples + +### Basic Table + +```json +{ + "type": "table", + "api": "/api/users", + "columns": [ + { "name": "id", "label": "ID", "width": 80 }, + { "name": "name", "label": "Name", "sortable": true }, + { "name": "email", "label": "Email", "sortable": true }, + { "name": "role", "label": "Role", "filterable": true }, + { "name": "createdAt", "label": "Created", "type": "date", "sortable": true } + ], + "rowActions": [ + { "label": "Edit", "onClick": { "type": "navigate", "url": "/users/${id}/edit" } }, + { "label": "Delete", "onClick": { "type": "api", "api": "/api/users/${id}", "method": "DELETE", "confirm": "Delete this user?" } } + ], + "pagination": true, + "pageSize": 20, + "searchable": true +} +``` + +### CRUD Table + +```json +{ + "type": "table", + "api": "/api/products", + "columns": [ + { "name": "name", "label": "Product Name" }, + { "name": "price", "label": "Price", "type": "number" }, + { "name": "stock", "label": "Stock", "type": "number" }, + { "name": "active", "label": "Active", "type": "boolean" } + ], + "filters": [ + { "name": "category", "label": "Category", "type": "select", "api": "/api/categories" }, + { "name": "priceRange", "label": "Price Range", "type": "input" } + ], + "selectable": true, + "batchActions": [ + { "label": "Delete Selected", "onClick": { "type": "api", "api": "/api/products/batch-delete", "method": "POST" } }, + { "label": "Export", "onClick": { "type": "download", "url": "/api/products/export" } } + ], + "rowActions": [ + { "label": "Edit", "onClick": { "type": "dialog", "title": "Edit Product", "body": { "type": "form", "fields": [...] } } }, + { "label": "Delete", "onClick": { "type": "api", "api": "/api/products/${id}", "method": "DELETE" } } + ] +} +``` + +### Static Data Table + +```json +{ + "type": "table", + "data": [ + { "id": 1, "name": "Alice", "role": "Admin" }, + { "id": 2, "name": "Bob", "role": "User" } + ], + "columns": [ + { "name": "id", "label": "ID" }, + { "name": "name", "label": "Name" }, + { "name": "role", "label": "Role" } + ] +} +``` + +## Features + +### Columns + +Each column can specify: + +- **type** - Data type for rendering (text, number, boolean, date, image) +- **sortable** - Enable sorting for this column +- **filterable** - Enable filtering for this column +- **width** - Fixed column width + +### Sorting + +Enable sorting on columns with `sortable: true`. Users can click column headers to sort. + +### Filtering + +Add filters for specific columns or use global search with `searchable: true`. + +### Pagination + +Enable pagination with `pagination: true` and set items per page with `pageSize`. + +### Row Actions + +Actions that apply to individual rows (edit, delete, view details, etc.). + +### Batch Actions + +Actions that apply to selected rows when `selectable: true`. + +### Expandable Rows + +Show additional details by setting `expandable` to a component definition. + +## Column Types + +- **text** - Plain text (default) +- **number** - Numeric values with proper alignment +- **boolean** - Checkmark or yes/no indicator +- **date** - Formatted date display +- **image** - Image thumbnail + +## Related Components + +- **[Page](/docs/03-objectui/container-components/page)** - Page container +- **[Form](/docs/03-objectui/container-components/form)** - Edit forms diff --git a/content/docs/cn/03-objectui/meta.json b/content/docs/cn/03-objectui/meta.json index 8ec6a9b..ae2903b 100644 --- a/content/docs/cn/03-objectui/meta.json +++ b/content/docs/cn/03-objectui/meta.json @@ -5,6 +5,9 @@ "index", "core-concepts", "component-spec", + "basic-components", + "container-components", + "actions", "renderer-usage" ] }