Displaying Timelines

Displaying Timelines & Activity Components

Purpose

This skill enables systematic creation of timeline and activity components, from simple vertical timelines to complex interactive Gantt charts. It provides clear decision frameworks based on use case and data characteristics, ensuring optimal performance, real-time updates, and accessible implementations.

When to Use

Activate this skill when:

• Creating activity feeds (social, notifications, audit logs)
• Displaying timelines (vertical, horizontal, interactive)
• Building Gantt charts or project schedules
• Implementing calendar interfaces (month, week, day views)
• Showing chronological events or historical data
• Handling real-time activity updates
• Requiring timestamp formatting (relative, absolute)
• Ensuring timeline accessibility or responsive behavior

Quick Decision Framework

Select component type based on use case:

Social Activity        → Activity Feed (infinite scroll, reactions)
System Events          → Audit Log (searchable, exportable, precise timestamps)
User Notifications     → Notification Feed (read/unread, grouped by date)
Historical Events      → Vertical Timeline (milestones, alternating sides)
Project Planning       → Gantt Chart (dependencies, drag-to-reschedule)
Scheduling             → Calendar Interface (month/week/day views)
Interactive Roadmap    → Horizontal Timeline (zoom, pan, filter)

For detailed selection criteria, reference references/component-selection.md.

Core Implementation Patterns

Activity Feeds

Social Feed Pattern:

• User avatar + name + action description
• Relative timestamps ("2 hours ago")
• Reactions and comments
• Infinite scroll with pagination
• Real-time updates via WebSocket
• Reference references/activity-feeds.md

Notification Feed Pattern:

• Grouped by date sections
• Read/unread states with indicators
• Mark all as read functionality
• Filter by notification type
• Action buttons (view, dismiss)
• Reference references/notification-feeds.md

Audit Log Pattern:

• System events with precise timestamps
• User action tracking
• Searchable with advanced filters
• Exportable (CSV, JSON)
• Security-focused display
• Reference references/audit-logs.md

Example: examples/social-activity-feed.tsx

Timeline Visualizations

Vertical Timeline:

• Events stacked chronologically
• Connecting line with marker dots
• Date markers and event cards
• Optional alternating sides
• Best for: Historical events, project milestones
• Reference references/vertical-timelines.md

Horizontal Timeline:

• Events along horizontal axis
• Scroll or zoom to navigate
• Density varies by zoom level
• Best for: Project timelines, roadmaps
• Reference references/horizontal-timelines.md

Interactive Timeline:

• Click events for detail view
• Filter by category/type
• Zoom in/out controls
• Pan and scroll navigation
• Best for: Data exploration, rich interactivity
• Reference references/interactive-timelines.md

Example: examples/milestone-timeline.tsx

Gantt Charts

Project Planning Features:

• Tasks as horizontal bars
• Dependencies with arrows
• Critical path highlighting
• Drag to reschedule
• Progress indicators
• Milestone markers (diamonds)
• Resource allocation
• Today marker line
• Zoom levels (day/week/month/year)

To generate Gantt chart data:

python scripts/generate_gantt_data.py --tasks 50 --dependencies auto

Reference references/gantt-patterns.md for implementation details.

Example: examples/project-gantt.tsx

Calendar Interfaces

Month View:

• Traditional calendar grid
• Events in date cells
• Click to create/edit
• Color-coded categories
• Multi-calendar overlay

Week View:

• Time slots (hourly)
• Events as draggable blocks
• Resize to change duration
• Multiple calendars overlay

Day/Agenda View:

• Detailed daily schedule
• List format with time duration
• Location and attendees
• Scrollable timeline

Reference references/calendar-patterns.md for all views.

Example: examples/calendar-scheduler.tsx

Timestamp Formatting

Essential timestamp patterns:

Relative (Recent Events):

• "Just now" (<1 min)
• "5 minutes ago"
• "3 hours ago"
• "Yesterday at 3:42 PM"

Absolute (Older Events):

• "Jan 15, 2025"
• "January 15, 2025 at 3:42 PM"
• ISO 8601 for APIs

Implementation Considerations:

• Timezone handling (display user's local time)
• Locale-aware formatting
• Hover for precise timestamp
• Auto-update relative times

To format timestamps consistently:

node scripts/format_timestamps.js --locale en-US --timezone auto

Reference references/timestamp-formatting.md for complete patterns.

Real-Time Updates

Live Activity Feed:

• WebSocket or SSE for new events
• Smooth insertion animation
• "X new items" notification banner
• Click to load new items
• Optimistic updates for user actions

Implementation Pattern:

1. Show user action immediately
2. Update timestamp to "Just now"
3. Send to server in background
4. Rollback if error occurs

Reference references/real-time-updates.md for WebSocket patterns.

Example: examples/realtime-activity.tsx

Performance Optimization

Critical performance thresholds:

<100 events       → Client-side rendering, no virtualization
100-1,000 events  → Virtual scrolling recommended
1,000+ events     → Virtual scrolling + server pagination
Real-time         → Debounce updates, batch insertions

Optimization Strategies:

• Memoize timeline item components
• Lazy load event details
• Virtual scrolling for long timelines
• Debounce real-time updates (batch every 500ms)
• Optimize timestamp calculations

To benchmark performance:

node scripts/benchmark_timeline.js --events 10000

Reference references/performance-optimization.md for details.