Skip to content

Commit 22ca625

Browse files
Copilothuangyiirene
Copilot
and
huangyiirene
committed
Add timeline component tests and comprehensive documentation
Co-authored-by: huangyiirene <7665279+huangyiirene@users.noreply.github.com>
1 parent c80121d commit 22ca625

2 files changed

Lines changed: 362 additions & 0 deletions

File tree

‎packages/components/src/new-components.test.ts‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,4 +62,13 @@ describe('New Components Registration', () => {
6262
expect(component?.label).toBe('Loading');
6363
});
6464
});
65+
66+
describe('Complex Components', () => {
67+
it('should register timeline component', () => {
68+
const component = ComponentRegistry.getConfig('timeline');
69+
expect(component).toBeDefined();
70+
expect(component?.label).toBe('Timeline');
71+
expect(component?.type).toBe('data-display');
72+
});
73+
});
6574
});

‎packages/components/src/renderers/complex/TIMELINE.md‎

Lines changed: 353 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,353 @@
1+
# Timeline Component
2+
3+
A comprehensive, feature-rich timeline component for Object UI that supports three distinct variants: vertical, horizontal, and Gantt-style (Airtable-like) timelines.
4+
5+
## Features
6+
7+
- 🎯 **Three Variants**: Vertical, Horizontal, and Gantt/Airtable-style timelines
8+
- 🎨 **Color Variants**: Support for default, success, warning, danger, and info colors
9+
- 📅 **Date Formatting**: Configurable date formats (short, long, ISO)
10+
- ⏱️ **Time Scales**: Gantt view supports day, week, and month scales
11+
- 🔄 **Interactive**: Click handlers for timeline items
12+
- 🎭 **Icon Support**: Add custom icons or emojis to timeline markers
13+
- 📊 **Multi-track**: Gantt view supports multiple rows/tracks
14+
- 🔢 **Auto-calculated**: Automatic date range calculation for Gantt view
15+
- 💅 **Tailwind CSS**: Fully styled with Tailwind, customizable with className
16+
17+
## Installation
18+
19+
The timeline component is included in `@object-ui/components`.
20+
21+
```bash
22+
npm install @object-ui/components @object-ui/react @object-ui/core
23+
```
24+
25+
## Usage
26+
27+
### Vertical Timeline
28+
29+
Perfect for showing project milestones, history, or chronological events.
30+
31+
```json
32+
{
33+
"type": "timeline",
34+
"variant": "vertical",
35+
"dateFormat": "long",
36+
"items": [
37+
{
38+
"time": "2024-01-15",
39+
"title": "Project Kickoff",
40+
"description": "Initial meeting with stakeholders and project planning",
41+
"variant": "success",
42+
"icon": "🚀"
43+
},
44+
{
45+
"time": "2024-02-01",
46+
"title": "Design Phase Complete",
47+
"description": "UI/UX designs approved and ready for development",
48+
"variant": "info",
49+
"icon": "🎨"
50+
},
51+
{
52+
"time": "2024-03-15",
53+
"title": "Beta Release",
54+
"description": "Internal testing phase begins",
55+
"variant": "warning",
56+
"icon": "⚡"
57+
},
58+
{
59+
"time": "2024-04-01",
60+
"title": "Official Launch",
61+
"description": "Product goes live to all users",
62+
"variant": "success",
63+
"icon": "🎉"
64+
}
65+
]
66+
}
67+
```
68+
69+
### Horizontal Timeline
70+
71+
Ideal for roadmaps, quarterly plans, or linear progressions.
72+
73+
```json
74+
{
75+
"type": "timeline",
76+
"variant": "horizontal",
77+
"dateFormat": "short",
78+
"items": [
79+
{
80+
"time": "2024-01-01",
81+
"title": "Q1 2024",
82+
"description": "Planning & Design",
83+
"variant": "success"
84+
},
85+
{
86+
"time": "2024-04-01",
87+
"title": "Q2 2024",
88+
"description": "Development",
89+
"variant": "info"
90+
},
91+
{
92+
"time": "2024-07-01",
93+
"title": "Q3 2024",
94+
"description": "Testing & QA",
95+
"variant": "warning"
96+
},
97+
{
98+
"time": "2024-10-01",
99+
"title": "Q4 2024",
100+
"description": "Launch & Scale",
101+
"variant": "success"
102+
}
103+
]
104+
}
105+
```
106+
107+
### Gantt Timeline (Airtable Style)
108+
109+
Perfect for project management, resource planning, and multi-track timelines.
110+
111+
```json
112+
{
113+
"type": "timeline",
114+
"variant": "gantt",
115+
"dateFormat": "short",
116+
"timeScale": "month",
117+
"rowLabel": "Project Tasks",
118+
"items": [
119+
{
120+
"label": "Backend Development",
121+
"items": [
122+
{
123+
"title": "API Design",
124+
"startDate": "2024-01-01",
125+
"endDate": "2024-01-31",
126+
"variant": "success"
127+
},
128+
{
129+
"title": "Database Schema",
130+
"startDate": "2024-01-15",
131+
"endDate": "2024-02-15",
132+
"variant": "info"
133+
},
134+
{
135+
"title": "API Implementation",
136+
"startDate": "2024-02-01",
137+
"endDate": "2024-03-31",
138+
"variant": "default"
139+
}
140+
]
141+
},
142+
{
143+
"label": "Frontend Development",
144+
"items": [
145+
{
146+
"title": "UI Design",
147+
"startDate": "2024-01-15",
148+
"endDate": "2024-02-15",
149+
"variant": "warning"
150+
},
151+
{
152+
"title": "Component Library",
153+
"startDate": "2024-02-01",
154+
"endDate": "2024-03-15",
155+
"variant": "info"
156+
},
157+
{
158+
"title": "Integration",
159+
"startDate": "2024-03-01",
160+
"endDate": "2024-04-15",
161+
"variant": "default"
162+
}
163+
]
164+
},
165+
{
166+
"label": "Testing & QA",
167+
"items": [
168+
{
169+
"title": "Unit Tests",
170+
"startDate": "2024-02-15",
171+
"endDate": "2024-03-15",
172+
"variant": "success"
173+
},
174+
{
175+
"title": "Integration Tests",
176+
"startDate": "2024-03-01",
177+
"endDate": "2024-04-01",
178+
"variant": "info"
179+
},
180+
{
181+
"title": "User Acceptance Testing",
182+
"startDate": "2024-04-01",
183+
"endDate": "2024-04-30",
184+
"variant": "danger"
185+
}
186+
]
187+
}
188+
]
189+
}
190+
```
191+
192+
## Props
193+
194+
### Common Props
195+
196+
| Prop | Type | Default | Description |
197+
|------|------|---------|-------------|
198+
| `variant` | `'vertical' \| 'horizontal' \| 'gantt'` | `'vertical'` | Timeline variant to render |
199+
| `dateFormat` | `'short' \| 'long' \| 'iso'` | `'short'` | Date formatting style |
200+
| `items` | `TimelineItem[]` | `[]` | Array of timeline items (structure varies by variant) |
201+
| `className` | `string` | - | Additional CSS classes |
202+
203+
### Vertical/Horizontal Item Props
204+
205+
| Prop | Type | Description |
206+
|------|------|-------------|
207+
| `time` | `string` | ISO date string (e.g., "2024-01-15") |
208+
| `title` | `string` | Item title |
209+
| `description` | `string` | Item description |
210+
| `variant` | `'default' \| 'success' \| 'warning' \| 'danger' \| 'info'` | Color variant |
211+
| `icon` | `string` | Icon or emoji to display in marker |
212+
| `content` | `SchemaNode` | Custom content schema |
213+
| `className` | `string` | Additional CSS classes |
214+
215+
### Gantt-Specific Props
216+
217+
| Prop | Type | Default | Description |
218+
|------|------|---------|-------------|
219+
| `timeScale` | `'day' \| 'week' \| 'month'` | `'month'` | Time scale for the timeline header |
220+
| `rowLabel` | `string` | `'Items'` | Label for the row header column |
221+
| `minDate` | `string` | Auto-calculated | Override minimum date (YYYY-MM-DD) |
222+
| `maxDate` | `string` | Auto-calculated | Override maximum date (YYYY-MM-DD) |
223+
224+
### Gantt Item Structure
225+
226+
```typescript
227+
{
228+
label: string; // Row label
229+
items: Array<{
230+
title: string; // Bar label
231+
startDate: string; // ISO date string
232+
endDate: string; // ISO date string
233+
variant?: string; // Color variant
234+
}>;
235+
}
236+
```
237+
238+
## Color Variants
239+
240+
The timeline component supports 5 color variants:
241+
242+
- `default` - Blue (default color)
243+
- `success` - Green
244+
- `warning` - Yellow/Orange
245+
- `danger` - Red
246+
- `info` - Purple
247+
248+
Each variant applies to markers (vertical/horizontal) or bars (Gantt).
249+
250+
## Date Formats
251+
252+
- `short` - MM/DD/YYYY (e.g., "1/15/2024")
253+
- `long` - Month DD, YYYY (e.g., "January 15, 2024")
254+
- `iso` - YYYY-MM-DD (e.g., "2024-01-15")
255+
256+
## Time Scales (Gantt Only)
257+
258+
- `day` - Daily granularity
259+
- `week` - Weekly granularity
260+
- `month` - Monthly granularity (default)
261+
262+
## Advanced Usage
263+
264+
### Custom Styling
265+
266+
Use Tailwind CSS classes for custom styling:
267+
268+
```json
269+
{
270+
"type": "timeline",
271+
"variant": "vertical",
272+
"className": "max-w-3xl mx-auto",
273+
"items": [
274+
{
275+
"time": "2024-01-15",
276+
"title": "Custom Styled Item",
277+
"className": "bg-blue-50 p-4 rounded-lg",
278+
"variant": "info"
279+
}
280+
]
281+
}
282+
```
283+
284+
### With Custom Content
285+
286+
You can add custom content schemas to vertical/horizontal timeline items:
287+
288+
```json
289+
{
290+
"type": "timeline",
291+
"variant": "vertical",
292+
"items": [
293+
{
294+
"time": "2024-01-15",
295+
"title": "Custom Content",
296+
"content": [
297+
{
298+
"type": "button",
299+
"label": "View Details",
300+
"className": "mt-2"
301+
}
302+
]
303+
}
304+
]
305+
}
306+
```
307+
308+
### Interactive Items
309+
310+
Handle item clicks in Gantt view:
311+
312+
```typescript
313+
// In React component
314+
<SchemaRenderer
315+
schema={{
316+
type: 'timeline',
317+
variant: 'gantt',
318+
onItemClick: (item, row, rowIndex, itemIndex) => {
319+
console.log('Clicked:', item.title, 'in row:', row.label);
320+
},
321+
items: [...]
322+
}}
323+
/>
324+
```
325+
326+
## UI Components
327+
328+
The timeline component is built using these base UI components:
329+
330+
### Vertical/Horizontal
331+
- `Timeline` - Container
332+
- `TimelineItem` - Individual item
333+
- `TimelineMarker` - Marker/dot
334+
- `TimelineContent` - Content wrapper
335+
- `TimelineTitle` - Title heading
336+
- `TimelineTime` - Time display
337+
- `TimelineDescription` - Description text
338+
339+
### Gantt
340+
- `TimelineGantt` - Container
341+
- `TimelineGanttHeader` - Header with time scale
342+
- `TimelineGanttRow` - Individual row
343+
- `TimelineGanttLabel` - Row label
344+
- `TimelineGanttBar` - Task bar
345+
- `TimelineGanttBarContent` - Bar content/text
346+
347+
## Examples
348+
349+
See the [prototype app](../../examples/prototype/src/App.tsx) for comprehensive examples of all three timeline variants in action.
350+
351+
## License
352+
353+
MIT

0 commit comments

Comments
 (0)