@volt-package/calendar-timeline

Week and Day timeline view plugin for Volt Calendar. Provides 24-hour timeline layouts with a sophisticated event overlap algorithm.

📦 Installation

npm install @volt-package/calendar-core @volt-package/calendar-timeline
# or
pnpm add @volt-package/calendar-core @volt-package/calendar-timeline

🚀 Usage

import { VoltCalendar } from '@volt-package/calendar-core';
import { TimelinePlugin } from '@volt-package/calendar-timeline';

const calendar = new VoltCalendar({
  plugins: [TimelinePlugin],
  initialView: 'week', // or 'day'
  events: [
    {
      id: '1',
      title: 'Meeting',
      start: '2025-12-15T10:00:00',
      end: '2025-12-15T11:30:00',
    },
  ],
});

calendar.subscribe((state) => {
  console.log('Timeline state:', state);
  // state.grid: Time slots for each day
  // state.events: Events with calculated positions (top, left, width, height)
});

📊 Features

Week View

• 7-day Timeline: Full week with 24-hour slots per day
• Smart Overlap: Google Calendar-style event positioning
• Column Packing: Automatically arranges overlapping events
• CSS Coordinates: Returns percentage-based positions

Day View

• Single Day: 24-hour timeline for focused view
• Same Algorithm: Uses the same overlap detection
• High Precision: Minute-level accuracy

🎨 Smart Overlap Algorithm

The Timeline plugin implements a sophisticated algorithm for handling overlapping events:

1. Cluster Detection

Groups events that overlap in time:

Events: [A: 10:00-11:00, B: 10:30-11:30, C: 14:00-15:00]
Clusters: [[A, B], [C]]

2. Column Assignment

Uses Graph Coloring algorithm to assign columns:

Cluster [A, B]:
  - A overlaps with B → different columns
  - Column 0: [A]
  - Column 1: [B]

3. Coordinate Calculation

Returns CSS percentage coordinates:

{
  style: {
    top: "41.67%",    // 10:00 = 41.67% of 24 hours
    height: "6.25%",  // 1.5 hours duration
    left: "0%",       // Column 0
    width: "50%",     // 2 columns total → 50% width
    zIndex: 1
  }
}

📐 Output Data

GridCell

Time slots for each day:

interface GridCell {
  date: Date; // e.g., 2025-12-15 10:00:00
  isToday: boolean;
  isOtherMonth: boolean; // Always false for timeline
  props: {
    'aria-label': string; // "12/15/2025 10:00"
    'data-date': string; // ISO format
  };
}

RenderedEvent

Events with calculated positions:

interface RenderedEvent {
  def: CalendarEventInput;
  style: {
    top: string; // "25.5%" - start time position
    height: string; // "12.5%" - duration
    left: string; // "0%" - column position
    width: string; // "33.33%" - width based on overlaps
    zIndex: number; // Layer order
  };
  isStart: boolean;
  isEnd: boolean;
}

🔧 API

TimelinePlugin

class TimelinePlugin {
  name = 'timeline';

  // Standard calculation
  calculate(store: Store, viewType: 'week' | 'day' = 'week'): ViewState;

  // With recurring event expansion
  calculateWithRecurrence(store: Store, viewType: 'week' | 'day' = 'week'): ViewState;
}

🧮 Overlap Algorithm Functions

Exported helper functions:

// Detect overlapping event clusters
detectClusters(events: CalendarEvent[]): EventCluster[];

// Calculate column width (percentage)
calculateColumnWidth(columnIndex: number, totalColumns: number): string;

// Calculate column position (percentage)
calculateColumnPosition(columnIndex: number, totalColumns: number): string;

// Calculate event height (percentage, 24-hour basis)
calculateEventHeight(start: Date, end: Date): string;

// Calculate event position (percentage, 00:00 basis)
calculateEventPosition(startTime: Date): string;

// Calculate expansion factor
calculateExpansionFactor(columnIndex: number, totalColumns: number): number;

📝 ViewState

{
  viewType: 'week' | 'day',
  currentDate: Date,
  dateRange: {
    start: Date, // Week/day start
    end: Date    // Week/day end
  },
  grid: GridCell[],      // 24-hour slots × days
  events: RenderedEvent[] // Positioned events with overlap handling
}

🎯 Use Cases

• Weekly/daily schedule views
• Time-based event management
• Meeting room scheduling
• Appointment booking
• Resource timeline views

🔗 Related Packages

• @volt-package/calendar-core - Core engine (required)
• @volt-package/calendar-month - Monthly grid view

📄 License

MIT

🤝 Contributing

Issues and PRs are welcome at volt-calendar.