@volt-package/calendar-month

Monthly calendar view plugin for Volt Calendar. Generates a 7x6 grid (42 cells) displaying a full month with previous/next month overflow.

📦 Installation

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

🚀 Usage

import { VoltCalendar } from '@volt-package/calendar-core';
import { MonthPlugin } from '@volt-package/calendar-month';

const calendar = new VoltCalendar({
  plugins: [MonthPlugin],
  initialView: 'month',
  events: [
    {
      id: '1',
      title: 'Meeting',
      start: '2025-12-15T10:00:00',
      end: '2025-12-15T11:00:00',
    },
  ],
});

calendar.subscribe((state) => {
  console.log('Month view state:', state);
  // state.grid: 42 GridCell objects
  // state.events: Events with calculated CSS positions
});

📊 Features

• 7x6 Grid Layout: 42 cells covering the entire month plus overflow days
• Previous/Next Month: Shows days from adjacent months in gray
• Event Positioning: Automatic positioning with simple stacking layout
• Today Indicator: Highlights current date
• Recurring Events: Automatic expansion of RRULE events
• Framework Agnostic: Works with React, Vue, vanilla JS, etc.

📐 Grid Structure

Sun  Mon  Tue  Wed  Thu  Fri  Sat
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
29   30   1    2    3    4    5     ← Previous month
6    7    8    9    10   11   12
13   14   15   16   17   18   19    ← Current month
20   21   22   23   24   25   26
27   28   29   30   31   1    2     ← Next month
3    4    5    6    7    8    9

🎨 Output Data

GridCell

Each cell in the grid:

interface GridCell {
  date: Date;
  isToday: boolean;
  isOtherMonth: boolean; // true for previous/next month days
  props: {
    'aria-label': string;
    'data-date': string; // ISO format
  };
}

RenderedEvent

Events with calculated positions:

interface RenderedEvent {
  def: CalendarEventInput;
  style: {
    top: string; // "0px", "20px", "40px" (stacked)
    height: string; // "18px"
    left: string; // "2px"
    width: string; // "calc(100% - 4px)"
    zIndex: number;
  };
  isStart: boolean;
  isEnd: boolean;
}

🔧 API

MonthPlugin

class MonthPlugin {
  name = 'month';
  calculate(store: Store): ViewState;
}

The calculate method:

1. Calculates month range (first Sunday to last Saturday)
2. Generates 42 grid cells
3. Retrieves events in range (including recurring events)
4. Calculates event positions
5. Returns ViewState with grid and events

📝 ViewState

{
  viewType: 'month',
  currentDate: Date,
  dateRange: {
    start: Date, // First day of grid
    end: Date    // Last day of grid
  },
  grid: GridCell[],      // 42 cells
  events: RenderedEvent[] // Positioned events
}

🎯 Use Cases

• Monthly calendar displays
• Event overview for a full month
• Date picker components
• Planning and scheduling apps

🔗 Related Packages

• @volt-package/calendar-core - Core engine (required)
• @volt-package/calendar-timeline - Week/Day timeline views

📄 License

MIT

🤝 Contributing

Issues and PRs are welcome at volt-calendar.