diff --git a/apps/site/app/components/InteractiveDemo.tsx b/apps/site/app/components/InteractiveDemo.tsx index 11b9b18b..4611368c 100644 --- a/apps/site/app/components/InteractiveDemo.tsx +++ b/apps/site/app/components/InteractiveDemo.tsx @@ -17,6 +17,12 @@ const pluginsLoading = typeof window !== 'undefined' import('@object-ui/plugin-charts'), import('@object-ui/plugin-kanban'), import('@object-ui/plugin-markdown'), + import('@object-ui/plugin-timeline'), + import('@object-ui/plugin-calendar'), + import('@object-ui/plugin-calendar-view'), + import('@object-ui/plugin-gantt'), + import('@object-ui/plugin-map'), + import('@object-ui/plugin-chatbot'), import('@object-ui/views'), ]) : Promise.resolve([]); diff --git a/apps/site/package.json b/apps/site/package.json index 03506954..ba069082 100644 --- a/apps/site/package.json +++ b/apps/site/package.json @@ -14,10 +14,16 @@ "@object-ui/components": "workspace:*", "@object-ui/core": "workspace:*", "@object-ui/plugin-aggrid": "workspace:*", + "@object-ui/plugin-calendar": "workspace:*", + "@object-ui/plugin-calendar-view": "workspace:*", "@object-ui/plugin-charts": "workspace:*", + "@object-ui/plugin-chatbot": "workspace:*", "@object-ui/plugin-editor": "workspace:*", + "@object-ui/plugin-gantt": "workspace:*", "@object-ui/plugin-kanban": "workspace:*", + "@object-ui/plugin-map": "workspace:*", "@object-ui/plugin-markdown": "workspace:*", + "@object-ui/plugin-timeline": "workspace:*", "@object-ui/views": "workspace:*", "@object-ui/react": "workspace:*", "@object-ui/types": "workspace:*", diff --git a/content/docs/plugins/index.md b/content/docs/plugins/index.md index 96ae943a..b282a2c4 100644 --- a/content/docs/plugins/index.md +++ b/content/docs/plugins/index.md @@ -11,20 +11,29 @@ ObjectUI plugins are lazy-loaded component packages that extend the framework wi Browse available plugins: -### [Charts Plugin](/docs/plugins/plugin-charts) -Data visualization with Recharts - Bar, Line, Area, and Pie charts +### Data Visualization -### [Editor Plugin](/docs/plugins/plugin-editor) -Code editor powered by Monaco Editor (VS Code's editor) +- **[Charts Plugin](/docs/plugins/plugin-charts)** - Bar, Line, Area, and Pie charts +- **[Timeline Plugin](/docs/plugins/plugin-timeline)** - Vertical, horizontal, and Gantt-style timelines +- **[Gantt Plugin](/docs/plugins/plugin-gantt)** - Project task visualization with dependencies (ObjectQL) +- **[Calendar View Plugin](/docs/plugins/plugin-calendar-view)** - Full calendar with month/week/day views +- **[Calendar Plugin](/docs/plugins/plugin-calendar)** - Calendar for ObjectQL data sources +- **[Map Plugin](/docs/plugins/plugin-map)** - Location visualization with markers (ObjectQL) -### [Kanban Plugin](/docs/plugins/plugin-kanban) -Kanban board with drag-and-drop functionality +### Content & Editing -### [Markdown Plugin](/docs/plugins/plugin-markdown) -Markdown renderer with GitHub Flavored Markdown support +- **[Editor Plugin](/docs/plugins/plugin-editor)** - Code editor powered by Monaco Editor +- **[Markdown Plugin](/docs/plugins/plugin-markdown)** - Markdown renderer with GFM support +- **[Chatbot Plugin](/docs/plugins/plugin-chatbot)** - Chat interface component -### [Views (Core Package)](/docs/views) -Advanced object data management and visualization +### Workflows & Tasks + +- **[Kanban Plugin](/docs/plugins/plugin-kanban)** - Kanban board with drag-and-drop +- **[AgGrid Plugin](/docs/plugins/plugin-aggrid)** - Advanced data grid + +### Core Packages + +- **[Views (Core Package)](/docs/views)** - Advanced object data management and visualization ## Official Plugins @@ -96,6 +105,125 @@ npm install @object-ui/plugin-markdown --- +### AgGrid Plugin + +**[@object-ui/plugin-aggrid](/docs/plugins/plugin-aggrid)** - Advanced data grid powered by AG Grid Community Edition. + +- Sorting, filtering, and pagination +- Row selection and editing +- Multiple themes +- Lazy-loaded + +```bash +npm install @object-ui/plugin-aggrid ag-grid-community ag-grid-react +``` + +[Read full documentation →](/docs/plugins/plugin-aggrid) + +--- + +### Timeline Plugin + +**[@object-ui/plugin-timeline](/docs/plugins/plugin-timeline)** - Timeline component with multiple layout variants. + +- Vertical, horizontal, and Gantt-style layouts +- Customizable markers with icons +- Date formatting options +- Time scales (day/week/month) + +```bash +npm install @object-ui/plugin-timeline +``` + +[Read full documentation →](/docs/plugins/plugin-timeline) + +--- + +### Chatbot Plugin + +**[@object-ui/plugin-chatbot](/docs/plugins/plugin-chatbot)** - Chat interface component with message history. + +- User and assistant message roles +- System messages +- Timestamps and avatars +- Auto-scroll and typing indicators + +```bash +npm install @object-ui/plugin-chatbot +``` + +[Read full documentation →](/docs/plugins/plugin-chatbot) + +--- + +### Calendar View Plugin + +**[@object-ui/plugin-calendar-view](/docs/plugins/plugin-calendar-view)** - Full-featured calendar with month, week, and day views. + +- Month, week, and day calendar views +- Event display with colors +- Navigation controls +- All-day and timed events + +```bash +npm install @object-ui/plugin-calendar-view +``` + +[Read full documentation →](/docs/plugins/plugin-calendar-view) + +--- + +### Calendar Plugin (ObjectQL) + +**[@object-ui/plugin-calendar](/docs/plugins/plugin-calendar)** - Calendar visualization for ObjectQL data sources. + +- ObjectQL integration +- Automatic field mapping +- Database-driven events +- Works with object/api/value providers + +```bash +npm install @object-ui/plugin-calendar +``` + +[Read full documentation →](/docs/plugins/plugin-calendar) + +--- + +### Gantt Plugin (ObjectQL) + +**[@object-ui/plugin-gantt](/docs/plugins/plugin-gantt)** - Gantt chart for ObjectQL data sources. + +- Project task visualization +- Progress tracking (0-100%) +- Task dependencies +- ObjectQL integration + +```bash +npm install @object-ui/plugin-gantt +``` + +[Read full documentation →](/docs/plugins/plugin-gantt) + +--- + +### Map Plugin (ObjectQL) + +**[@object-ui/plugin-map](/docs/plugins/plugin-map)** - Map visualization for ObjectQL data sources. + +- Location-based markers +- Latitude/longitude support +- Marker customization +- ObjectQL integration + +```bash +npm install @object-ui/plugin-map +``` + +[Read full documentation →](/docs/plugins/plugin-map) + +--- + ### Views (Core Package) **[@object-ui/views](/docs/views)** - Core views package for advanced object data management and visualization. @@ -142,12 +270,19 @@ export const CodeEditorRenderer = (props) => ( ### Bundle Impact -| Plugin | Initial Load | Lazy Load | -|--------|-------------|-----------| -| plugin-editor | ~0.2 KB | ~20 KB | -| plugin-charts | ~0.2 KB | ~540 KB | -| plugin-kanban | ~0.2 KB | ~100-150 KB | -| plugin-markdown | ~0.2 KB | ~100-200 KB | +| Plugin | Initial Load | Lazy Load | Description | +|--------|-------------|-----------|-------------| +| plugin-editor | ~0.2 KB | ~20 KB | Monaco editor | +| plugin-charts | ~0.2 KB | ~540 KB | Recharts visualization | +| plugin-kanban | ~0.2 KB | ~100-150 KB | Drag-and-drop board | +| plugin-markdown | ~0.2 KB | ~100-200 KB | Markdown rendering | +| plugin-aggrid | ~0.2 KB | ~280 KB | Data grid | +| plugin-timeline | ~0.2 KB | ~10 KB | Timeline layouts | +| plugin-chatbot | ~0.2 KB | ~30 KB | Chat interface | +| plugin-calendar-view | ~0.2 KB | ~40 KB | Full calendar | +| plugin-calendar | ~0.2 KB | ~50 KB | ObjectQL calendar | +| plugin-gantt | ~0.2 KB | ~60 KB | ObjectQL Gantt | +| plugin-map | ~0.2 KB | ~20 KB | ObjectQL map | Without lazy loading, all this code would be in your main bundle! diff --git a/content/docs/plugins/meta.json b/content/docs/plugins/meta.json index 88d54b1e..cdebca92 100644 --- a/content/docs/plugins/meta.json +++ b/content/docs/plugins/meta.json @@ -2,9 +2,15 @@ "title": "Plugins", "pages": [ "plugin-aggrid", + "plugin-calendar", + "plugin-calendar-view", "plugin-charts", + "plugin-chatbot", "plugin-editor", + "plugin-gantt", "plugin-kanban", - "plugin-markdown" + "plugin-map", + "plugin-markdown", + "plugin-timeline" ] } diff --git a/content/docs/plugins/plugin-calendar-view.mdx b/content/docs/plugins/plugin-calendar-view.mdx new file mode 100644 index 00000000..5bb50e1f --- /dev/null +++ b/content/docs/plugins/plugin-calendar-view.mdx @@ -0,0 +1,530 @@ +--- +title: "Plugin Calendar View" +--- + +import { InteractiveDemo } from '@/app/components/InteractiveDemo'; + +Full-featured calendar component with month, week, and day views for displaying events and scheduling. + +## Installation + +```bash +npm install @object-ui/plugin-calendar-view +``` + +## Interactive Examples + +### Month View + + + +### Week View + + + +### Day View + + + +## Usage + +### Basic Usage + +```tsx +// Import once in your app entry point +import '@object-ui/plugin-calendar-view' + +// Use in schemas +const schema = { + type: 'calendar-view', + view: 'month', + data: [ + { + id: 1, + title: 'Team Meeting', + start: '2024-01-15T10:00:00', + end: '2024-01-15T11:00:00', + color: '#3b82f6' + } + ] +} +``` + +## Features + +- **Three View Modes**: Month, week, and day calendar views +- **Event Display**: Show events with titles, times, and colors +- **Navigation**: Previous/next navigation and "Today" button +- **View Switcher**: Easy switching between month, week, day views +- **Event Interaction**: Click events to trigger actions +- **Date Selection**: Click dates to create new events +- **All-day Events**: Support for all-day and timed events +- **Color Coding**: Custom colors per event +- **Responsive**: Adapts to different screen sizes + +## Schema API + +```typescript +{ + type: 'calendar-view', + view?: 'month' | 'week' | 'day', + data?: Array, + titleField?: string, + startDateField?: string, + endDateField?: string, + allDayField?: string, + colorField?: string, + colorMapping?: Record, + currentDate?: string, + allowCreate?: boolean, + onEventClick?: (event: any) => void, + onDateClick?: (date: Date) => void, + onViewChange?: (view: string) => void, + onNavigate?: (date: Date) => void, + className?: string +} +``` + +### Calendar Event Data + +```typescript +{ + id: string | number, + title: string, // or use custom titleField + start: string, // ISO date string + end?: string, // ISO date string (optional) + allDay?: boolean, + color?: string, // Hex color or Tailwind class + [key: string]: any // Additional custom fields +} +``` + +## Properties + +| Property | Type | Default | Description | +|----------|------|---------|-------------| +| `view` | string | `'month'` | Calendar view mode: month, week, or day | +| `data` | array | `[]` | Array of event objects | +| `titleField` | string | `'title'` | Field name for event title | +| `startDateField` | string | `'start'` | Field name for event start date | +| `endDateField` | string | `'end'` | Field name for event end date | +| `allDayField` | string | `'allDay'` | Field name for all-day flag | +| `colorField` | string | `'color'` | Field name for event color | +| `colorMapping` | object | - | Map field values to colors | +| `currentDate` | string | today | ISO date for initial display | +| `allowCreate` | boolean | `false` | Enable event creation on date click | +| `onEventClick` | function | - | Callback when event is clicked | +| `onDateClick` | function | - | Callback when date is clicked | +| `onViewChange` | function | - | Callback when view changes | +| `onNavigate` | function | - | Callback when date navigation occurs | +| `className` | string | `''` | Additional Tailwind CSS classes | + +## Examples + +### Meeting Scheduler + +```tsx +const scheduler = { + type: 'calendar-view', + view: 'week', + data: [ + { + id: 1, + title: '1:1 with Sarah', + start: '2024-01-15T10:00:00', + end: '2024-01-15T10:30:00', + color: '#3b82f6', + type: 'meeting' + }, + { + id: 2, + title: 'Team Standup', + start: '2024-01-15T09:00:00', + end: '2024-01-15T09:15:00', + color: '#10b981', + type: 'meeting' + }, + { + id: 3, + title: 'Product Review', + start: '2024-01-16T14:00:00', + end: '2024-01-16T15:30:00', + color: '#8b5cf6', + type: 'meeting' + } + ], + className: 'h-[700px] border rounded-lg shadow-sm' +} +``` + +### Event Calendar + +```tsx +const eventCalendar = { + type: 'calendar-view', + view: 'month', + data: [ + { + id: 1, + title: 'Tech Conference 2024', + start: '2024-03-15', + end: '2024-03-17', + color: '#f59e0b', + allDay: true, + category: 'conference' + }, + { + id: 2, + title: 'Workshop: React Best Practices', + start: '2024-03-20', + color: '#3b82f6', + allDay: true, + category: 'workshop' + }, + { + id: 3, + title: 'Hackathon Weekend', + start: '2024-03-25', + end: '2024-03-26', + color: '#10b981', + allDay: true, + category: 'hackathon' + } + ], + colorMapping: { + conference: '#f59e0b', + workshop: '#3b82f6', + hackathon: '#10b981' + }, + className: 'h-[650px] border-2 rounded-xl' +} +``` + +### Project Timeline + +```tsx +const projectTimeline = { + type: 'calendar-view', + view: 'month', + data: [ + { + id: 1, + name: 'Design Phase', + startDate: '2024-01-01', + endDate: '2024-01-15', + color: '#8b5cf6', + allDay: true + }, + { + id: 2, + name: 'Development Sprint 1', + startDate: '2024-01-16', + endDate: '2024-01-31', + color: '#3b82f6', + allDay: true + }, + { + id: 3, + name: 'Testing & QA', + startDate: '2024-02-01', + endDate: '2024-02-10', + color: '#f59e0b', + allDay: true + }, + { + id: 4, + name: 'Launch', + startDate: '2024-02-15', + color: '#10b981', + allDay: true + } + ], + titleField: 'name', + startDateField: 'startDate', + endDateField: 'endDate', + className: 'h-[600px] border rounded-lg' +} +``` + +## Field Mapping + +Map your data structure to calendar fields: + +```tsx +const schema = { + type: 'calendar-view', + data: [ + { + id: 1, + eventName: 'Meeting', // Custom field + begins: '2024-01-15', // Custom field + ends: '2024-01-15', // Custom field + bgcolor: '#3b82f6' // Custom field + } + ], + titleField: 'eventName', // Map to custom field + startDateField: 'begins', // Map to custom field + endDateField: 'ends', // Map to custom field + colorField: 'bgcolor' // Map to custom field +} +``` + +## Color Mapping + +Map categories to colors: + +```tsx +const schema = { + type: 'calendar-view', + data: [ + { id: 1, title: 'Meeting', start: '2024-01-15', category: 'work' }, + { id: 2, title: 'Birthday', start: '2024-01-20', category: 'personal' } + ], + colorField: 'category', + colorMapping: { + work: '#3b82f6', // Blue + personal: '#10b981', // Green + urgent: '#ef4444' // Red + } +} +``` + +## Event Handling + +### Event Click + +```tsx +const schema = { + type: 'calendar-view', + data: [...], + onEventClick: (event) => { + console.log('Event clicked:', event); + // Show event details modal + // Or navigate to event page + } +} +``` + +### Date Click + +```tsx +const schema = { + type: 'calendar-view', + data: [...], + allowCreate: true, + onDateClick: (date) => { + console.log('Date clicked:', date); + // Show create event dialog + // Pre-fill with selected date + } +} +``` + +### View Change + +```tsx +const schema = { + type: 'calendar-view', + onViewChange: (view) => { + console.log('View changed to:', view); + // Update URL or state + } +} +``` + +### Navigation + +```tsx +const schema = { + type: 'calendar-view', + onNavigate: (date) => { + console.log('Navigated to:', date); + // Fetch events for new date range + } +} +``` + +## Customization + +### Container Sizing + +```tsx +const schema = { + type: 'calendar-view', + className: 'h-[600px] border-2 border-gray-200 rounded-xl shadow-lg', + data: [...] +} +``` + +### Responsive Heights + +```tsx +const schema = { + type: 'calendar-view', + className: 'h-[400px] sm:h-[500px] lg:h-[700px] border rounded-lg', + data: [...] +} +``` + +## TypeScript Support + +```typescript +import type { CalendarViewSchema, CalendarEvent } from '@object-ui/types' + +const events: CalendarEvent[] = [ + { + id: 1, + title: 'Meeting', + start: new Date('2024-01-15T10:00:00'), + end: new Date('2024-01-15T11:00:00'), + color: '#3b82f6' + } +] + +const calendarSchema: CalendarViewSchema = { + type: 'calendar-view', + view: 'month', + data: events, + onEventClick: (event) => console.log(event) +} +``` + +## Related Documentation + +- [Plugin System Overview](/docs/concepts/plugins) +- [Package README](https://github.com/objectstack-ai/objectui/tree/main/packages/plugin-calendar-view) diff --git a/content/docs/plugins/plugin-calendar.mdx b/content/docs/plugins/plugin-calendar.mdx new file mode 100644 index 00000000..f8060e13 --- /dev/null +++ b/content/docs/plugins/plugin-calendar.mdx @@ -0,0 +1,311 @@ +--- +title: "Plugin Calendar" +--- + +Calendar view component for ObjectQL data sources - displays database records as calendar events. + +## Installation + +```bash +npm install @object-ui/plugin-calendar +``` + +## Overview + +The `@object-ui/plugin-calendar` plugin provides calendar visualization for ObjectQL data sources. It's designed to work with object-based data providers and automatically maps record fields to calendar events. + +**Note**: This plugin is designed for use with ObjectQL data sources. For a standalone calendar component, see [Calendar View Plugin](/docs/plugins/plugin-calendar-view). + +## Features + +- **ObjectQL Integration**: Works seamlessly with object/api/value data providers +- **Automatic Field Mapping**: Maps database fields to calendar events +- **Multiple View Modes**: Month, week, and day calendar views +- **Date Filtering**: Automatically filters records by date range +- **Event Interaction**: Click handling for events and dates +- **Color Coding**: Support for event color customization + +## Usage + +### Basic Usage with ObjectQL + +```tsx +import '@object-ui/plugin-calendar' + +const schema = { + type: 'object-calendar', + objectName: 'events', // Your ObjectQL object + calendar: { + startDateField: 'startDate', + endDateField: 'endDate', + titleField: 'title', + colorField: 'category' + } +} +``` + +### With Static Data + +```tsx +const schema = { + type: 'object-calendar', + staticData: [ + { + id: 1, + title: 'Team Meeting', + startDate: '2024-01-15T10:00:00', + endDate: '2024-01-15T11:00:00', + category: 'meeting' + }, + { + id: 2, + title: 'Project Deadline', + startDate: '2024-01-20', + category: 'deadline' + } + ], + calendar: { + startDateField: 'startDate', + endDateField: 'endDate', + titleField: 'title', + colorField: 'category' + } +} +``` + +## Schema API + +```typescript +{ + type: 'object-calendar', + objectName?: string, // ObjectQL object name + staticData?: Array, // Static data array + data?: ViewData, // Advanced data configuration + calendar?: CalendarConfig, // Calendar-specific configuration + onEventClick?: (record: any) => void, + onDateClick?: (date: Date) => void, + className?: string +} +``` + +### CalendarConfig + +```typescript +{ + startDateField: string, // Field containing event start date + endDateField?: string, // Field containing event end date + titleField: string, // Field to use as event title + colorField?: string, // Field for color coding + descriptionField?: string // Field for event description +} +``` + +## Configuration + +### Field Mapping + +Map your database fields to calendar properties: + +```tsx +{ + type: 'object-calendar', + objectName: 'tasks', + calendar: { + titleField: 'taskName', // Database field for title + startDateField: 'dueDate', // Database field for start + endDateField: 'completedAt', // Database field for end + colorField: 'priority' // Database field for color + } +} +``` + +### Data Providers + +#### Object Provider (Database) + +```tsx +{ + type: 'object-calendar', + objectName: 'appointments', + calendar: { + startDateField: 'scheduledAt', + titleField: 'subject' + } +} +``` + +#### Value Provider (Static) + +```tsx +{ + type: 'object-calendar', + staticData: [ + { id: 1, title: 'Event 1', date: '2024-01-15' }, + { id: 2, title: 'Event 2', date: '2024-01-20' } + ], + calendar: { + startDateField: 'date', + titleField: 'title' + } +} +``` + +#### API Provider + +```tsx +{ + type: 'object-calendar', + data: { + provider: 'api', + endpoint: '/api/events', + method: 'GET' + }, + calendar: { + startDateField: 'startTime', + endDateField: 'endTime', + titleField: 'eventName' + } +} +``` + +## Event Handling + +### Event Click + +```tsx +{ + type: 'object-calendar', + objectName: 'events', + calendar: { + startDateField: 'start', + titleField: 'title' + }, + onEventClick: (record) => { + console.log('Event clicked:', record); + // Open event details + // Navigate to event page + } +} +``` + +### Date Click + +```tsx +{ + type: 'object-calendar', + objectName: 'events', + calendar: { + startDateField: 'start', + titleField: 'title' + }, + onDateClick: (date) => { + console.log('Date clicked:', date); + // Create new event on this date + } +} +``` + +## Examples + +### Appointment Scheduler + +```tsx +const appointmentCalendar = { + type: 'object-calendar', + objectName: 'appointments', + calendar: { + startDateField: 'appointmentDate', + endDateField: 'appointmentEnd', + titleField: 'patientName', + descriptionField: 'notes', + colorField: 'appointmentType' + }, + onEventClick: (appointment) => { + // Show appointment details + } +} +``` + +### Event Management + +```tsx +const eventCalendar = { + type: 'object-calendar', + objectName: 'events', + calendar: { + startDateField: 'eventStart', + endDateField: 'eventEnd', + titleField: 'eventTitle', + colorField: 'eventCategory' + }, + onEventClick: (event) => { + // Navigate to event details + }, + onDateClick: (date) => { + // Create new event + } +} +``` + +### Task Deadlines + +```tsx +const taskCalendar = { + type: 'object-calendar', + objectName: 'tasks', + calendar: { + startDateField: 'dueDate', + titleField: 'taskTitle', + colorField: 'priority' + }, + onEventClick: (task) => { + // Open task details + } +} +``` + +## Comparison with Calendar View Plugin + +| Feature | object-calendar | calendar-view | +|---------|----------------|---------------| +| **Data Source** | ObjectQL (database) | Static arrays | +| **Use Case** | Dynamic data from backend | Pre-loaded event data | +| **Field Mapping** | Configurable field names | Standard field names | +| **Data Loading** | Automatic via ObjectQL | Manual via props | +| **Best For** | Database-driven apps | Static schedules | + +**When to use object-calendar**: +- You're using ObjectQL for data management +- Events come from a database or API +- You need automatic data fetching and filtering + +**When to use calendar-view**: +- You have static or pre-loaded event data +- You're not using ObjectQL +- You need a simple, standalone calendar + +## TypeScript Support + +```typescript +import type { ObjectGridSchema, CalendarConfig } from '@object-ui/types' + +const calendarConfig: CalendarConfig = { + startDateField: 'startDate', + endDateField: 'endDate', + titleField: 'title', + colorField: 'category' +} + +const calendarSchema: ObjectGridSchema = { + type: 'object-calendar', + objectName: 'events', + calendar: calendarConfig +} +``` + +## Related Documentation + +- [Calendar View Plugin](/docs/plugins/plugin-calendar-view) - Standalone calendar component +- [Plugin System Overview](/docs/concepts/plugins) +- [Views Package](/docs/views) - ObjectQL data management +- [Package README](https://github.com/objectstack-ai/objectui/tree/main/packages/plugin-calendar) diff --git a/content/docs/plugins/plugin-chatbot.mdx b/content/docs/plugins/plugin-chatbot.mdx new file mode 100644 index 00000000..c5aaad7b --- /dev/null +++ b/content/docs/plugins/plugin-chatbot.mdx @@ -0,0 +1,466 @@ +--- +title: "Plugin Chatbot" +--- + +import { InteractiveDemo } from '@/app/components/InteractiveDemo'; + +Chat interface component with message history, typing indicators, and customizable avatars. + +## Installation + +```bash +npm install @object-ui/plugin-chatbot +``` + +## Interactive Examples + +### Basic Chatbot + + + +### Chatbot with Timestamps + + + +### Customer Support Chat + + + +## Usage + +### Basic Usage + +```tsx +// Import once in your app entry point +import '@object-ui/plugin-chatbot' + +// Use in schemas +const schema = { + type: 'chatbot', + messages: [ + { + id: '1', + role: 'assistant', + content: 'Hello! How can I help you?' + } + ], + placeholder: 'Type your message...', + autoResponse: true +} +``` + +## Features + +- **Message History**: Display chat messages with user and assistant roles +- **System Messages**: Show system notifications in the chat +- **Timestamps**: Optional timestamp display for each message +- **Custom Avatars**: Configurable avatar images and fallback text +- **Auto-scroll**: Automatically scroll to newest messages +- **Typing Indicator**: Built-in typing indicator component +- **Auto-response**: Demo mode with automatic responses +- **Lightweight**: Pure React components with minimal dependencies + +## Schema API + +```typescript +{ + type: 'chatbot', + messages?: ChatMessage[], + placeholder?: string, + showTimestamp?: boolean, + disabled?: boolean, + userAvatarUrl?: string, + userAvatarFallback?: string, + assistantAvatarUrl?: string, + assistantAvatarFallback?: string, + maxHeight?: string, + autoResponse?: boolean, + autoResponseText?: string, + autoResponseDelay?: number, + onSend?: (content: string, messages: ChatMessage[]) => void, + className?: string +} +``` + +### ChatMessage + +```typescript +{ + id: string, + role: 'user' | 'assistant' | 'system', + content: string, + timestamp?: string, + avatar?: string, + avatarFallback?: string +} +``` + +## Properties + +| Property | Type | Default | Description | +|----------|------|---------|-------------| +| `messages` | array | `[]` | Initial chat messages | +| `placeholder` | string | `'Type your message...'` | Input field placeholder text | +| `showTimestamp` | boolean | `false` | Display timestamps for messages | +| `disabled` | boolean | `false` | Disable chat input | +| `userAvatarUrl` | string | - | URL for user avatar image | +| `userAvatarFallback` | string | `'You'` | Fallback text for user avatar | +| `assistantAvatarUrl` | string | - | URL for assistant avatar image | +| `assistantAvatarFallback` | string | `'AI'` | Fallback text for assistant avatar | +| `maxHeight` | string | `'500px'` | Maximum chat container height | +| `autoResponse` | boolean | `false` | Enable auto-response (demo mode) | +| `autoResponseText` | string | - | Text for auto-response | +| `autoResponseDelay` | number | `1000` | Delay before auto-response (ms) | +| `onSend` | function | - | Callback when message is sent | +| `className` | string | `''` | Additional Tailwind CSS classes | + +## Message Roles + +### User Messages + +Messages from the user appear on the right side with primary styling: + +```tsx +{ + id: '1', + role: 'user', + content: 'Hello!', + timestamp: '10:30 AM' +} +``` + +### Assistant Messages + +Messages from the assistant appear on the left side: + +```tsx +{ + id: '2', + role: 'assistant', + content: 'Hi! How can I help?', + timestamp: '10:30 AM' +} +``` + +### System Messages + +System messages appear centered with muted styling: + +```tsx +{ + id: '3', + role: 'system', + content: 'Chat session started' +} +``` + +## Examples + +### Simple AI Chat + +```tsx +const aiChat = { + type: 'chatbot', + messages: [ + { + id: 'welcome', + role: 'assistant', + content: 'Hello! I\'m your AI assistant. Ask me anything!' + } + ], + placeholder: 'Ask me a question...', + assistantAvatarFallback: 'AI', + userAvatarFallback: 'You', + autoResponse: true, + autoResponseText: 'That\'s a great question! Let me think about that...', + maxHeight: '600px' +} +``` + +### Support Ticket Chat + +```tsx +const supportChat = { + type: 'chatbot', + messages: [ + { + id: 'sys-1', + role: 'system', + content: 'Ticket #12345 - Account Access Issue' + }, + { + id: '1', + role: 'assistant', + content: 'Hi! I\'m here to help with your account access issue.', + avatarFallback: 'SP', + timestamp: '2:15 PM' + } + ], + placeholder: 'Describe your issue...', + showTimestamp: true, + userAvatarFallback: 'JD', + assistantAvatarFallback: 'SP', + className: 'w-full max-w-3xl mx-auto' +} +``` + +### Sales Bot + +```tsx +const salesBot = { + type: 'chatbot', + messages: [ + { + id: '1', + role: 'assistant', + content: 'Welcome! I\'m here to help you find the perfect product. What are you looking for today?', + avatarFallback: 'SB' + } + ], + placeholder: 'Tell us what you need...', + assistantAvatarFallback: 'SB', + userAvatarFallback: 'You', + autoResponse: true, + autoResponseText: 'Great choice! Let me show you some options...', + autoResponseDelay: 1200, + maxHeight: '500px', + className: 'border-2 border-primary rounded-xl' +} +``` + +### Multi-agent Chat + +```tsx +const multiAgentChat = { + type: 'chatbot', + messages: [ + { + id: '1', + role: 'assistant', + content: 'Hello! Sarah from Sales here.', + avatarFallback: 'SA' + }, + { + id: '2', + role: 'user', + content: 'I need help with pricing', + avatarFallback: 'CU' + }, + { + id: '3', + role: 'system', + content: 'Transferring to Finance team...' + }, + { + id: '4', + role: 'assistant', + content: 'Hi! Mike from Finance. I can help with that.', + avatarFallback: 'MI' + } + ], + showTimestamp: true, + userAvatarFallback: 'CU' +} +``` + +## Custom Avatars + +### Avatar Images + +```tsx +const schema = { + type: 'chatbot', + userAvatarUrl: 'https://example.com/user-avatar.jpg', + assistantAvatarUrl: 'https://example.com/bot-avatar.jpg', + messages: [...] +} +``` + +### Avatar Fallbacks + +When images aren't available, fallback text is displayed: + +```tsx +const schema = { + type: 'chatbot', + userAvatarFallback: 'JD', // User initials + assistantAvatarFallback: 'AI', // Bot identifier + messages: [...] +} +``` + +### Per-message Avatars + +Override avatars for individual messages: + +```tsx +{ + id: '1', + role: 'assistant', + content: 'Message content', + avatar: 'https://example.com/special-avatar.jpg', + avatarFallback: 'SP' +} +``` + +## Event Handling + +### onSend Callback + +Handle message sending in your application: + +```tsx +const schema = { + type: 'chatbot', + messages: [...], + onSend: (content, allMessages) => { + console.log('User sent:', content); + console.log('All messages:', allMessages); + + // Send to your backend + fetch('/api/chat', { + method: 'POST', + body: JSON.stringify({ message: content }) + }); + } +} +``` + +## Customization + +### Container Styling + +```tsx +const schema = { + type: 'chatbot', + className: 'w-full max-w-2xl mx-auto border-2 rounded-xl shadow-lg', + maxHeight: '600px', + messages: [...] +} +``` + +### Responsive Heights + +```tsx +const schema = { + type: 'chatbot', + maxHeight: '400px', // or use Tailwind: 'h-96' + className: 'sm:max-h-[500px] lg:max-h-[600px]', + messages: [...] +} +``` + +## TypeScript Support + +```typescript +import type { ChatbotSchema, ChatMessage } from '@object-ui/types' + +const messages: ChatMessage[] = [ + { + id: '1', + role: 'assistant', + content: 'Hello!' + } +] + +const chatbotSchema: ChatbotSchema = { + type: 'chatbot', + messages, + placeholder: 'Type here...', + showTimestamp: true +} +``` + +## Related Documentation + +- [Plugin System Overview](/docs/concepts/plugins) +- [Package README](https://github.com/objectstack-ai/objectui/tree/main/packages/plugin-chatbot) diff --git a/content/docs/plugins/plugin-gantt.mdx b/content/docs/plugins/plugin-gantt.mdx new file mode 100644 index 00000000..56929c2e --- /dev/null +++ b/content/docs/plugins/plugin-gantt.mdx @@ -0,0 +1,397 @@ +--- +title: "Plugin Gantt" +--- + +Gantt chart component for ObjectQL data sources - visualizes project tasks, timelines, and dependencies. + +## Installation + +```bash +npm install @object-ui/plugin-gantt +``` + +## Overview + +The `@object-ui/plugin-gantt` plugin provides Gantt chart visualization for ObjectQL data sources. It's designed to work with object-based data providers and automatically maps record fields to Gantt chart tasks. + +**Note**: This plugin is designed for use with ObjectQL data sources. For a simpler timeline component, see [Timeline Plugin](/docs/plugins/plugin-timeline). + +## Features + +- **ObjectQL Integration**: Works seamlessly with object/api/value data providers +- **Automatic Field Mapping**: Maps database fields to Gantt tasks +- **Task Timeline**: Visual bars showing task duration +- **Progress Tracking**: Display task completion percentage (0-100%) +- **Dependencies**: Visualize task dependencies and relationships +- **Date Ranges**: Automatic date range calculation +- **Interactive**: Click handling for tasks + +## Usage + +### Basic Usage with ObjectQL + +```tsx +import '@object-ui/plugin-gantt' + +const schema = { + type: 'object-gantt', + objectName: 'tasks', // Your ObjectQL object + gantt: { + startDateField: 'startDate', + endDateField: 'endDate', + titleField: 'taskName', + progressField: 'completion', + dependenciesField: 'dependencies' + } +} +``` + +### With Static Data + +```tsx +const schema = { + type: 'object-gantt', + staticData: [ + { + id: 1, + taskName: 'Design Phase', + startDate: '2024-01-01', + endDate: '2024-01-15', + completion: 100 + }, + { + id: 2, + taskName: 'Development', + startDate: '2024-01-16', + endDate: '2024-02-28', + completion: 60, + dependencies: [1] + }, + { + id: 3, + taskName: 'Testing', + startDate: '2024-03-01', + endDate: '2024-03-15', + completion: 0, + dependencies: [2] + } + ], + gantt: { + startDateField: 'startDate', + endDateField: 'endDate', + titleField: 'taskName', + progressField: 'completion', + dependenciesField: 'dependencies' + } +} +``` + +## Schema API + +```typescript +{ + type: 'object-gantt', + objectName?: string, // ObjectQL object name + staticData?: Array, // Static data array + data?: ViewData, // Advanced data configuration + gantt?: GanttConfig, // Gantt-specific configuration + onTaskClick?: (record: any) => void, + className?: string +} +``` + +### GanttConfig + +```typescript +{ + startDateField: string, // Field containing task start date + endDateField: string, // Field containing task end date + titleField: string, // Field to use as task title + progressField?: string, // Field for progress (0-100) + dependenciesField?: string // Field for task dependencies (array of IDs) +} +``` + +## Configuration + +### Field Mapping + +Map your database fields to Gantt properties: + +```tsx +{ + type: 'object-gantt', + objectName: 'project_tasks', + gantt: { + titleField: 'name', // Database field for task name + startDateField: 'starts_at', // Database field for start date + endDateField: 'ends_at', // Database field for end date + progressField: 'percent_done', // Database field for progress + dependenciesField: 'depends_on' // Database field for dependencies + } +} +``` + +### Progress Field + +The progress field should contain a number between 0-100 representing the completion percentage: + +```tsx +{ + id: 1, + taskName: 'Development', + startDate: '2024-01-01', + endDate: '2024-02-01', + completion: 75 // 75% complete +} +``` + +### Dependencies Field + +The dependencies field should contain an array of task IDs that this task depends on: + +```tsx +[ + { + id: 1, + taskName: 'Design', + startDate: '2024-01-01', + endDate: '2024-01-15', + dependencies: [] // No dependencies + }, + { + id: 2, + taskName: 'Development', + startDate: '2024-01-16', + endDate: '2024-02-28', + dependencies: [1] // Depends on task 1 (Design) + }, + { + id: 3, + taskName: 'Testing', + startDate: '2024-03-01', + endDate: '2024-03-15', + dependencies: [2] // Depends on task 2 (Development) + } +] +``` + +## Data Providers + +### Object Provider (Database) + +```tsx +{ + type: 'object-gantt', + objectName: 'project_tasks', + gantt: { + startDateField: 'start_date', + endDateField: 'due_date', + titleField: 'title', + progressField: 'progress' + } +} +``` + +### Value Provider (Static) + +```tsx +{ + type: 'object-gantt', + staticData: [ + { id: 1, title: 'Task 1', start: '2024-01-01', end: '2024-01-15' }, + { id: 2, title: 'Task 2', start: '2024-01-16', end: '2024-01-31' } + ], + gantt: { + startDateField: 'start', + endDateField: 'end', + titleField: 'title' + } +} +``` + +### API Provider + +```tsx +{ + type: 'object-gantt', + data: { + provider: 'api', + endpoint: '/api/project/tasks', + method: 'GET' + }, + gantt: { + startDateField: 'startDate', + endDateField: 'endDate', + titleField: 'taskName', + progressField: 'percentComplete' + } +} +``` + +## Event Handling + +### Task Click + +```tsx +{ + type: 'object-gantt', + objectName: 'tasks', + gantt: { + startDateField: 'start', + endDateField: 'end', + titleField: 'name' + }, + onTaskClick: (task) => { + console.log('Task clicked:', task); + // Open task details + // Edit task + // Show task dependencies + } +} +``` + +## Examples + +### Software Project + +```tsx +const softwareProject = { + type: 'object-gantt', + objectName: 'sprint_tasks', + gantt: { + startDateField: 'startDate', + endDateField: 'endDate', + titleField: 'taskTitle', + progressField: 'completionPercent', + dependenciesField: 'blockedBy' + }, + onTaskClick: (task) => { + // Show task details modal + } +} +``` + +### Construction Project + +```tsx +const constructionGantt = { + type: 'object-gantt', + objectName: 'construction_phases', + gantt: { + startDateField: 'phase_start', + endDateField: 'phase_end', + titleField: 'phase_name', + progressField: 'percent_complete' + }, + onTaskClick: (phase) => { + // Navigate to phase details + } +} +``` + +### Marketing Campaign + +```tsx +const campaignGantt = { + type: 'object-gantt', + staticData: [ + { + id: 1, + activity: 'Market Research', + start: '2024-01-01', + end: '2024-01-14', + done: 100 + }, + { + id: 2, + activity: 'Content Creation', + start: '2024-01-15', + end: '2024-02-15', + done: 80, + requires: [1] + }, + { + id: 3, + activity: 'Campaign Launch', + start: '2024-02-16', + end: '2024-02-29', + done: 0, + requires: [2] + }, + { + id: 4, + activity: 'Performance Analysis', + start: '2024-03-01', + end: '2024-03-15', + done: 0, + requires: [3] + } + ], + gantt: { + titleField: 'activity', + startDateField: 'start', + endDateField: 'end', + progressField: 'done', + dependenciesField: 'requires' + } +} +``` + +## Comparison with Timeline Plugin + +| Feature | object-gantt | timeline (gantt variant) | +|---------|-------------|--------------------------| +| **Data Source** | ObjectQL (database) | Static arrays | +| **Dependencies** | Yes | No | +| **Progress** | Yes (0-100%) | No | +| **Use Case** | Project management | Simple timelines | +| **Field Mapping** | Configurable | Fixed schema | +| **Best For** | Database-driven projects | Static presentations | + +**When to use object-gantt**: +- You're using ObjectQL for data management +- You need task dependencies and progress tracking +- Tasks come from a database or API +- You're building project management features + +**When to use timeline (gantt variant)**: +- You have static timeline data +- You don't need dependencies or progress +- You're creating simple visual timelines +- You're not using ObjectQL + +## Typical Use Cases + +1. **Project Management**: Track project tasks, milestones, and dependencies +2. **Sprint Planning**: Visualize agile sprint tasks and their timeline +3. **Construction Planning**: Display construction phases and their relationships +4. **Event Planning**: Show event preparation tasks and schedules +5. **Product Roadmap**: Display product features and release timelines + +## TypeScript Support + +```typescript +import type { ObjectGridSchema, GanttConfig } from '@object-ui/types' + +const ganttConfig: GanttConfig = { + startDateField: 'startDate', + endDateField: 'endDate', + titleField: 'taskName', + progressField: 'completion', + dependenciesField: 'dependencies' +} + +const ganttSchema: ObjectGridSchema = { + type: 'object-gantt', + objectName: 'project_tasks', + gantt: ganttConfig +} +``` + +## Related Documentation + +- [Timeline Plugin](/docs/plugins/plugin-timeline) - Simpler timeline visualization +- [Plugin System Overview](/docs/concepts/plugins) +- [Views Package](/docs/views) - ObjectQL data management +- [Package README](https://github.com/objectstack-ai/objectui/tree/main/packages/plugin-gantt) diff --git a/content/docs/plugins/plugin-map.mdx b/content/docs/plugins/plugin-map.mdx new file mode 100644 index 00000000..0326d3eb --- /dev/null +++ b/content/docs/plugins/plugin-map.mdx @@ -0,0 +1,456 @@ +--- +title: "Plugin Map" +--- + +Map visualization component for ObjectQL data sources - displays database records as map markers based on location data. + +## Installation + +```bash +npm install @object-ui/plugin-map +``` + +## Overview + +The `@object-ui/plugin-map` plugin provides map visualization for ObjectQL data sources. It's designed to work with object-based data providers and automatically maps record fields to map markers/pins. + +**Note**: This is a basic implementation suitable for simple use cases. For production applications with advanced mapping needs, consider integrating a dedicated mapping library like Mapbox, Leaflet, or Google Maps. + +## Features + +- **ObjectQL Integration**: Works seamlessly with object/api/value data providers +- **Automatic Field Mapping**: Maps database fields to map markers +- **Location Support**: Handle latitude/longitude or combined location fields +- **Marker Customization**: Configurable marker titles and descriptions +- **Marker Clustering**: Group nearby markers (when many points) +- **Popup/Tooltip**: Show details on marker click +- **Interactive**: Click handling for markers + +## Usage + +### Basic Usage with ObjectQL + +```tsx +import '@object-ui/plugin-map' + +const schema = { + type: 'object-map', + objectName: 'locations', // Your ObjectQL object + map: { + latitudeField: 'lat', + longitudeField: 'lng', + titleField: 'name', + descriptionField: 'address' + } +} +``` + +### With Static Data + +```tsx +const schema = { + type: 'object-map', + staticData: [ + { + id: 1, + name: 'Office HQ', + lat: 37.7749, + lng: -122.4194, + address: '123 Main St, San Francisco, CA' + }, + { + id: 2, + name: 'Warehouse', + lat: 37.8044, + lng: -122.2711, + address: '456 Oak Ave, Oakland, CA' + } + ], + map: { + latitudeField: 'lat', + longitudeField: 'lng', + titleField: 'name', + descriptionField: 'address' + } +} +``` + +## Schema API + +```typescript +{ + type: 'object-map', + objectName?: string, // ObjectQL object name + staticData?: Array, // Static data array + data?: ViewData, // Advanced data configuration + map?: MapConfig, // Map-specific configuration + onMarkerClick?: (record: any) => void, + className?: string +} +``` + +### MapConfig + +```typescript +{ + latitudeField?: string, // Field containing latitude + longitudeField?: string, // Field containing longitude + locationField?: string, // Field with combined location (alternative) + titleField?: string, // Field to use as marker title + descriptionField?: string, // Field for marker description + zoom?: number, // Default zoom level (1-20) + center?: [number, number] // Center coordinates [lat, lng] +} +``` + +## Configuration + +### Field Mapping - Separate Coordinates + +When your data has separate latitude and longitude fields: + +```tsx +{ + type: 'object-map', + objectName: 'stores', + map: { + latitudeField: 'latitude', + longitudeField: 'longitude', + titleField: 'storeName', + descriptionField: 'storeAddress' + } +} +``` + +### Field Mapping - Combined Location + +When your data has a combined location field: + +```tsx +{ + type: 'object-map', + objectName: 'places', + map: { + locationField: 'coordinates', // e.g., "37.7749,-122.4194" or {lat: 37.7749, lng: -122.4194} + titleField: 'placeName', + descriptionField: 'description' + } +} +``` + +### Zoom and Center + +Control the initial map view: + +```tsx +{ + type: 'object-map', + objectName: 'locations', + map: { + latitudeField: 'lat', + longitudeField: 'lng', + titleField: 'name', + zoom: 12, // Zoom level (1-20) + center: [37.7749, -122.4194] // [latitude, longitude] + } +} +``` + +## Data Providers + +### Object Provider (Database) + +```tsx +{ + type: 'object-map', + objectName: 'retail_stores', + map: { + latitudeField: 'store_lat', + longitudeField: 'store_lng', + titleField: 'store_name', + descriptionField: 'store_address' + } +} +``` + +### Value Provider (Static) + +```tsx +{ + type: 'object-map', + staticData: [ + { id: 1, name: 'Location 1', lat: 37.7749, lng: -122.4194 }, + { id: 2, name: 'Location 2', lat: 37.8044, lng: -122.2711 } + ], + map: { + latitudeField: 'lat', + longitudeField: 'lng', + titleField: 'name' + } +} +``` + +### API Provider + +```tsx +{ + type: 'object-map', + data: { + provider: 'api', + endpoint: '/api/locations', + method: 'GET' + }, + map: { + latitudeField: 'latitude', + longitudeField: 'longitude', + titleField: 'locationName' + } +} +``` + +## Event Handling + +### Marker Click + +```tsx +{ + type: 'object-map', + objectName: 'locations', + map: { + latitudeField: 'lat', + longitudeField: 'lng', + titleField: 'name' + }, + onMarkerClick: (location) => { + console.log('Marker clicked:', location); + // Show location details + // Navigate to location page + // Open directions + } +} +``` + +## Examples + +### Store Locator + +```tsx +const storeLocator = { + type: 'object-map', + objectName: 'retail_locations', + map: { + latitudeField: 'latitude', + longitudeField: 'longitude', + titleField: 'storeName', + descriptionField: 'fullAddress', + zoom: 10, + center: [37.7749, -122.4194] // San Francisco + }, + onMarkerClick: (store) => { + // Show store details + // Display hours, phone, etc. + } +} +``` + +### Delivery Tracking + +```tsx +const deliveryMap = { + type: 'object-map', + objectName: 'active_deliveries', + map: { + latitudeField: 'current_lat', + longitudeField: 'current_lng', + titleField: 'driver_name', + descriptionField: 'delivery_address' + }, + onMarkerClick: (delivery) => { + // Show delivery details + // Contact driver + } +} +``` + +### Real Estate Listings + +```tsx +const propertyMap = { + type: 'object-map', + objectName: 'properties', + map: { + latitudeField: 'property_lat', + longitudeField: 'property_lng', + titleField: 'property_address', + descriptionField: 'property_details', + zoom: 12 + }, + onMarkerClick: (property) => { + // Show property details + // Display photos, price, etc. + } +} +``` + +### Event Venues + +```tsx +const venueMap = { + type: 'object-map', + staticData: [ + { + id: 1, + venueName: 'Conference Center', + lat: 37.7833, + lng: -122.4167, + details: 'Capacity: 500 people' + }, + { + id: 2, + venueName: 'Exhibition Hall', + lat: 37.7891, + lng: -122.3894, + details: 'Capacity: 1000 people' + }, + { + id: 3, + venueName: 'Outdoor Amphitheater', + lat: 37.7694, + lng: -122.4862, + details: 'Capacity: 2000 people' + } + ], + map: { + latitudeField: 'lat', + longitudeField: 'lng', + titleField: 'venueName', + descriptionField: 'details', + zoom: 11 + }, + onMarkerClick: (venue) => { + // Show venue details + // Book venue + } +} +``` + +### Field Service Map + +```tsx +const serviceMap = { + type: 'object-map', + objectName: 'service_calls', + map: { + latitudeField: 'customer_latitude', + longitudeField: 'customer_longitude', + titleField: 'customer_name', + descriptionField: 'service_type', + zoom: 10 + }, + onMarkerClick: (serviceCall) => { + // Show service call details + // Assign technician + // Get directions + } +} +``` + +## Typical Use Cases + +1. **Store Locator**: Display retail store locations +2. **Fleet Tracking**: Show vehicle or delivery locations +3. **Real Estate**: Display property listings on a map +4. **Event Venues**: Show event or venue locations +5. **Field Service**: Track service calls or technician locations +6. **Customer Locations**: Visualize customer distribution +7. **Asset Tracking**: Show location of equipment or assets + +## Location Data Formats + +### Separate Fields + +```tsx +{ + id: 1, + name: 'Location', + latitude: 37.7749, + longitude: -122.4194 +} +``` + +### Combined String + +```tsx +{ + id: 1, + name: 'Location', + coordinates: '37.7749,-122.4194' +} +``` + +### Object Format + +```tsx +{ + id: 1, + name: 'Location', + location: { + lat: 37.7749, + lng: -122.4194 + } +} +``` + +## Map Controls + +The map typically includes: +- **Zoom controls**: Zoom in/out buttons +- **Pan**: Drag to move around the map +- **Marker click**: Click markers to show details +- **Auto-fit**: Automatically adjust view to show all markers + +## Integration with Full-featured Map Libraries + +For production applications, you may want to integrate with: + +- **Mapbox**: Advanced styling, 3D maps, routing +- **Google Maps**: Street view, directions, extensive POI data +- **Leaflet**: Open-source, lightweight, customizable +- **OpenStreetMap**: Free, community-driven map data + +This plugin provides a basic implementation. For advanced features like: +- Directions/routing +- Street view +- 3D buildings +- Traffic data +- Custom map styles +- Advanced geocoding + +Consider using one of the full-featured mapping libraries above. + +## TypeScript Support + +```typescript +import type { ObjectGridSchema, MapConfig } from '@object-ui/types' + +const mapConfig: MapConfig = { + latitudeField: 'lat', + longitudeField: 'lng', + titleField: 'name', + descriptionField: 'description', + zoom: 12, + center: [37.7749, -122.4194] +} + +const mapSchema: ObjectGridSchema = { + type: 'object-map', + objectName: 'locations', + map: mapConfig +} +``` + +## Related Documentation + +- [Plugin System Overview](/docs/concepts/plugins) +- [Views Package](/docs/views) - ObjectQL data management +- [Package README](https://github.com/objectstack-ai/objectui/tree/main/packages/plugin-map) diff --git a/content/docs/plugins/plugin-timeline.mdx b/content/docs/plugins/plugin-timeline.mdx new file mode 100644 index 00000000..9503faa7 --- /dev/null +++ b/content/docs/plugins/plugin-timeline.mdx @@ -0,0 +1,464 @@ +--- +title: "Plugin Timeline" +--- + +import { InteractiveDemo } from '@/app/components/InteractiveDemo'; + +Timeline component with vertical, horizontal, and Gantt-style layouts for displaying events and project timelines. + +## Installation + +```bash +npm install @object-ui/plugin-timeline +``` + +## Interactive Examples + +### Vertical Timeline + + + +### Horizontal Timeline + + + +### Gantt-Style Timeline + + + +## Usage + +### Basic Usage + +```tsx +// Import once in your app entry point +import '@object-ui/plugin-timeline' + +// Use in schemas - Vertical Timeline +const schema = { + type: 'timeline', + variant: 'vertical', + items: [ + { + time: '2024-01-15', + title: 'Project Started', + description: 'Kickoff meeting', + variant: 'success' + } + ] +} +``` + +## Features + +- **Three Layout Variants**: Vertical, horizontal, and Gantt-style layouts +- **Customizable Markers**: Color-coded markers with icon support +- **Date Formatting**: Multiple date format options +- **Gantt Charts**: Project timeline visualization with task bars +- **Time Scales**: Day, week, or month scales for Gantt view +- **Lightweight**: Pure CSS and React components + +## Schema API + +### Timeline Schema + +```typescript +{ + type: 'timeline', + variant?: 'vertical' | 'horizontal' | 'gantt', + items?: TimelineItem[], + dateFormat?: 'short' | 'long' | 'iso', + // Gantt-specific + timeScale?: 'day' | 'week' | 'month', + rowLabel?: string, + minDate?: string, + maxDate?: string, + className?: string +} +``` + +### Timeline Item (Vertical/Horizontal) + +```typescript +{ + time: string, // ISO date string + title: string, + description?: string, + variant?: 'default' | 'success' | 'warning' | 'danger' | 'info', + icon?: string, // Emoji or text + content?: SchemaNode, // Custom React content + className?: string +} +``` + +### Gantt Item + +```typescript +{ + label: string, // Row label + items: Array<{ + title: string, + startDate: string, // ISO date string + endDate: string, // ISO date string + variant?: 'default' | 'success' | 'warning' | 'danger' | 'info' + }> +} +``` + +## Properties + +| Property | Type | Default | Description | +|----------|------|---------|-------------| +| `variant` | string | `'vertical'` | Timeline layout: vertical, horizontal, or gantt | +| `items` | array | `[]` | Array of timeline items | +| `dateFormat` | string | `'short'` | Date formatting: short, long, or iso | +| `timeScale` | string | `'month'` | Gantt time scale: day, week, or month | +| `rowLabel` | string | `'Items'` | Label for Gantt rows | +| `minDate` | string | auto | Override min date for Gantt (YYYY-MM-DD) | +| `maxDate` | string | auto | Override max date for Gantt (YYYY-MM-DD) | +| `className` | string | `''` | Additional Tailwind CSS classes | + +## Variants + +### Marker Variants + +Available marker/bar colors: + +- `default` - Gray +- `success` - Green +- `info` - Blue +- `warning` - Yellow +- `danger` - Red + +```tsx +const item = { + time: '2024-01-15', + title: 'Important Milestone', + variant: 'success' // Green marker +} +``` + +## Examples + +### Product Roadmap + +```tsx +const roadmap = { + type: 'timeline', + variant: 'horizontal', + dateFormat: 'long', + items: [ + { + time: '2024-01-01', + title: 'Alpha Release', + description: 'Internal testing phase', + variant: 'info', + icon: '🔬' + }, + { + time: '2024-03-01', + title: 'Beta Launch', + description: 'Limited public beta', + variant: 'warning', + icon: '🚀' + }, + { + time: '2024-06-01', + title: 'Public Launch', + description: 'General availability', + variant: 'success', + icon: '🎉' + } + ] +} +``` + +### Project Schedule (Gantt) + +```tsx +const schedule = { + type: 'timeline', + variant: 'gantt', + timeScale: 'week', + rowLabel: 'Teams', + items: [ + { + label: 'Design Team', + items: [ + { + title: 'Wireframes', + startDate: '2024-01-01', + endDate: '2024-01-14', + variant: 'info' + }, + { + title: 'Mockups', + startDate: '2024-01-15', + endDate: '2024-02-01', + variant: 'success' + } + ] + }, + { + label: 'Engineering', + items: [ + { + title: 'Development', + startDate: '2024-02-01', + endDate: '2024-03-31', + variant: 'warning' + } + ] + } + ] +} +``` + +### Company History + +```tsx +const history = { + type: 'timeline', + variant: 'vertical', + dateFormat: 'long', + items: [ + { + time: '2020-01-01', + title: 'Company Founded', + description: 'Started in a garage with 2 founders', + variant: 'success', + icon: '🏢' + }, + { + time: '2021-06-01', + title: 'Series A Funding', + description: 'Raised $5M from VCs', + variant: 'info', + icon: '💰' + }, + { + time: '2022-12-01', + title: '10,000 Customers', + description: 'Reached major milestone', + variant: 'success', + icon: '🎯' + }, + { + time: '2024-01-01', + title: 'Series B Funding', + description: 'Raised $20M to expand globally', + variant: 'warning', + icon: '🌍' + } + ] +} +``` + +## Date Formatting + +The timeline component supports three date formats: + +```tsx +// Short format: "1/15/2024" +{ dateFormat: 'short' } + +// Long format: "January 15, 2024" +{ dateFormat: 'long' } + +// ISO format: "2024-01-15" +{ dateFormat: 'iso' } +``` + +## Time Scales (Gantt) + +For Gantt-style timelines, choose the appropriate time scale: + +```tsx +// Day scale - for short projects +{ timeScale: 'day' } + +// Week scale - for medium projects +{ timeScale: 'week' } + +// Month scale - for long projects +{ timeScale: 'month' } +``` + +## Customization + +### Custom Icons + +```tsx +const item = { + time: '2024-01-15', + title: 'Milestone', + icon: '🎯', // Any emoji or short text + variant: 'success' +} +``` + +### Custom Colors + +Use Tailwind CSS classes for additional styling: + +```tsx +const schema = { + type: 'timeline', + variant: 'vertical', + className: 'max-w-4xl mx-auto', + items: [...] +} +``` + +## TypeScript Support + +```typescript +import type { TimelineSchema } from '@object-ui/types' + +const timelineSchema: TimelineSchema = { + type: 'timeline', + variant: 'vertical', + items: [ + { + time: '2024-01-15', + title: 'Event', + description: 'Description', + variant: 'success' + } + ] +} +``` + +## Related Documentation + +- [Plugin System Overview](/docs/concepts/plugins) +- [Package README](https://github.com/objectstack-ai/objectui/tree/main/packages/plugin-timeline) diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 8e4219d0..17edbb6f 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -117,18 +117,36 @@ importers: '@object-ui/plugin-aggrid': specifier: workspace:* version: link:../../packages/plugin-aggrid + '@object-ui/plugin-calendar': + specifier: workspace:* + version: link:../../packages/plugin-calendar + '@object-ui/plugin-calendar-view': + specifier: workspace:* + version: link:../../packages/plugin-calendar-view '@object-ui/plugin-charts': specifier: workspace:* version: link:../../packages/plugin-charts + '@object-ui/plugin-chatbot': + specifier: workspace:* + version: link:../../packages/plugin-chatbot '@object-ui/plugin-editor': specifier: workspace:* version: link:../../packages/plugin-editor + '@object-ui/plugin-gantt': + specifier: workspace:* + version: link:../../packages/plugin-gantt '@object-ui/plugin-kanban': specifier: workspace:* version: link:../../packages/plugin-kanban + '@object-ui/plugin-map': + specifier: workspace:* + version: link:../../packages/plugin-map '@object-ui/plugin-markdown': specifier: workspace:* version: link:../../packages/plugin-markdown + '@object-ui/plugin-timeline': + specifier: workspace:* + version: link:../../packages/plugin-timeline '@object-ui/react': specifier: workspace:* version: link:../../packages/react