# Plugin Timeline Timeline component with vertical, horizontal, and Gantt-style layouts for displaying events and project timelines. ## Installation [#installation] ```bash npm install @object-ui/plugin-timeline ``` ## Interactive Examples [#interactive-examples] ### Vertical Timeline [#vertical-timeline] ### Horizontal Timeline [#horizontal-timeline] ### Gantt-Style Timeline [#gantt-style-timeline] ## Usage [#usage] ### Basic Usage [#basic-usage] ```tsx // Import once in your app entry point import '@object-ui/plugin-timeline' import type { TimelineSchema } from '@object-ui/types' // Use in schemas - Vertical Timeline const schema: TimelineSchema = { type: 'timeline', variant: 'vertical', items: [ { time: '2024-01-15', title: 'Project Started', description: 'Kickoff meeting', variant: 'success' } ] } ``` ## Features [#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**: Hour, day, week, month, quarter, or year scales for Gantt view * **Lightweight**: Pure CSS and React components ## Schema API [#schema-api] ### Timeline Schema [#timeline-schema] ```plaintext { type: 'timeline', variant?: 'vertical' | 'horizontal' | 'gantt', items?: TimelineItem[], dateFormat?: 'short' | 'long' | 'iso', // Gantt-specific scale?: 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year', rowLabel?: string, minDate?: string, maxDate?: string, className?: string } ``` ### Timeline Item (Vertical/Horizontal) [#timeline-item-verticalhorizontal] ```plaintext { 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 [#gantt-item] ```plaintext { 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 [#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 | | `scale` | string | `'month'` | Gantt axis bucket: hour, day, week, month, quarter, or year | | `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 | Every key above is declared on the exported `TimelineSchema`, so an editor completes them and a wrong value is a type error. `scale` is the canonical axis key and the only one — it is `@objectstack/spec`'s `ui/TimelineConfig.json` spelling and the one the renderer reads. `timeScale`, the pre-spec spelling of `scale`, is **retired** (objectui#6355). It is no longer read, and it is no longer authorable: the key is tombstoned on `TimelineSchema`, so writing it is a type error and a validation failure rather than a chart that quietly falls back to the `month` default. Rename the key to `scale` — the accepted values are unchanged. `events`, `orientation` and `position` are also declared on `TimelineSchema` and are **read by nothing**. A timeline authored with `events` renders an empty rail — use `items`. They are deprecated and scheduled for removal. ## Variants [#variants] ### Marker 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 [#examples] ### Product Roadmap [#product-roadmap] ```tsx import type { TimelineSchema } from '@object-ui/types' const roadmap: TimelineSchema = { 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) [#project-schedule-gantt] ```tsx import type { TimelineSchema } from '@object-ui/types' const schedule: TimelineSchema = { type: 'timeline', variant: 'gantt', scale: '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 [#company-history] ```tsx import type { TimelineSchema } from '@object-ui/types' const history: TimelineSchema = { 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 [#date-formatting] The timeline component supports three date formats: ```tsx import type { TimelineSchema } from '@object-ui/types' const short: TimelineSchema['dateFormat'] = 'short' // "1/15/2024" const long: TimelineSchema['dateFormat'] = 'long' // "January 15, 2024" const iso: TimelineSchema['dateFormat'] = 'iso' // "2024-01-15" ``` ## Time Scales (Gantt) [#time-scales-gantt] For Gantt-style timelines, choose the appropriate time scale: ```tsx import type { TimelineSchema } from '@object-ui/types' const shortProject: TimelineSchema['scale'] = 'day' // short projects const mediumProject: TimelineSchema['scale'] = 'week' // medium projects const longProject: TimelineSchema['scale'] = 'month' // long projects ``` ## Customization [#customization] ### Custom Icons [#custom-icons] ```tsx const item = { time: '2024-01-15', title: 'Milestone', icon: '🎯', // Any emoji or short text variant: 'success' } ``` ### Custom Colors [#custom-colors] Use Tailwind CSS classes for additional styling: ```tsx import type { TimelineSchema } from '@object-ui/types' const schema: TimelineSchema = { type: 'timeline', variant: 'vertical', className: 'max-w-4xl mx-auto', items: [ { time: '2024-01-15', title: 'Milestone', variant: 'success' } ] } ``` ## TypeScript Support [#typescript-support] ```plaintext 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 [#related-documentation] * [Plugin System Overview](/docs/guide/plugins) * [Package README](https://github.com/objectstack-ai/objectui/tree/main/packages/plugin-timeline)