@zealic/full-event-calendar

A flexible and feature-rich React calendar component with multiple view types and comprehensive event management.

Features

• Multiple View Types: Day, Week, Month, Year, and List views
• Event Management: Full CRUD operations with optimistic updates
• Internationalization: Built-in support for multiple languages
• Touch Support: Swipe gestures for mobile devices
• Customizable: Extensive configuration options
• TypeScript: Full TypeScript support with comprehensive type definitions
• Accessible: ARIA-compliant and keyboard navigable
• Responsive: Works seamlessly on desktop and mobile devices

Installation

# Using yarn
yarn add @zealic/full-event-calendar

# Using npm
npm install @zealic/full-event-calendar

Peer Dependencies

This package requires React 17+ or React 18+:

# If not already installed
yarn add react react-dom

Basic Usage

Quick Start

import React from 'react';
import { MyEventCalendar } from '@zealic/full-event-calendar';
import '@zealic/full-event-calendar/styles.css';

function App() {
  return (
    <div className='App'>
      <MyEventCalendar />
    </div>
  );
}

export default App;

Advanced Usage with Custom Event Management

import React from 'react';
import {
  EventCalendar,
  useEventCalendar,
  CalendarEventType,
  EventCalendarConfigType,
} from '@zealic/full-event-calendar';
import '@zealic/full-event-calendar/styles.css';

const config: EventCalendarConfigType = {
  defaultView: 'month',
  use24HourFormatByDefault: true,
  monthView: {
    viewType: 'detailed',
    showOnlyCurrentMonth: true,
  },
};

function CustomCalendar() {
  const handleEventAdd = async (event: Omit<CalendarEventType, 'id'>) => {
    // Call your API to create event
    const response = await fetch('/api/events', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(event),
    });
    return response.json();
  };

  const handleEventUpdate = async (event: CalendarEventType) => {
    // Call your API to update event
    const response = await fetch(`/api/events/${event.id}`, {
      method: 'PUT',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(event),
    });
    return response.json();
  };

  const handleEventDelete = async (eventId: string) => {
    // Call your API to delete event
    await fetch(`/api/events/${eventId}`, {
      method: 'DELETE',
    });
  };

  const { events, isLoading, addEvent, updateEvent, deleteEvent, onViewOrDateChange } = useEventCalendar({
    config: { events: { allowUserRetryAfterFailure: true } },
    initialEvents: [], // Your initial events
    onEventAdd: handleEventAdd,
    onEventUpdate: handleEventUpdate,
    onEventDelete: handleEventDelete,
  });

  return (
    <EventCalendar
      config={config}
      events={events}
      isLoading={isLoading}
      onEventAdd={addEvent}
      onEventUpdate={updateEvent}
      onEventDelete={deleteEvent}
      onDateRangeChange={onViewOrDateChange}
    />
  );
}

API Reference

Components

EventCalendar

The main calendar component.

Props:

• config?: EventCalendarConfigType - Calendar configuration
• events: CalendarEventType[] - Array of events to display
• isLoading?: boolean - Loading state
• onEventAdd: (event: Omit<CalendarEventType, 'id'>) => Promise<void> - Event creation handler
• onEventUpdate: (event: CalendarEventType) => Promise<void> - Event update handler
• onEventDelete: (eventId: string) => Promise<void> - Event deletion handler
• onDateRangeChange?: (startDate: Date, endDate: Date) => Promise<void> - Date range change handler

MyEventCalendar

A pre-configured calendar component with built-in event management.

Hooks

useEventCalendar

Hook for managing calendar state and event operations.

Parameters:

• config?: EventCalendarHookConfig - Hook configuration
• initialEvents?: CalendarEventType[] - Initial events
• onEventAdd?: (event: Omit<CalendarEventType, 'id'>) => Promise<CalendarEventType> - Event creation handler
• onEventUpdate?: (event: CalendarEventType) => Promise<CalendarEventType> - Event update handler
• onEventDelete?: (eventId: string) => Promise<void> - Event deletion handler
• onDateRangeChange?: (startDate: Date, endDate: Date) => Promise<CalendarEventType[]> - Date range change handler

Returns:

• events: CalendarEventType[] - Current events
• isLoading: boolean - Loading state
• addEvent: (event: Omit<CalendarEventType, 'id'>) => Promise<void> - Add event function
• updateEvent: (event: CalendarEventType) => Promise<void> - Update event function
• deleteEvent: (eventId: string) => Promise<void> - Delete event function
• onViewOrDateChange: (startDate: Date, endDate: Date) => Promise<void> - View/date change handler

Types

CalendarEventType

interface CalendarEventType {
  id: string;
  title: string;
  description?: string;
  startDate: Date;
  endDate: Date;
  color: string;
  isAllDay?: boolean;
  isRepeating?: boolean;
  resourceId?: string;
  eventType?: string;
  visibility?: 'public' | 'private';
  // ... other properties
}

Internationalization

The component supports multiple languages out of the box:

import { enUS, fr, es, da, nbNO, ptBR, svSE } from '@zealic/full-event-calendar';

const config: EventCalendarConfigType = {
  localization: fr, // Use French localization
  // ... other config
};

Available locales:

• enUS - English (US)
• fr - French
• es - Spanish
• da - Danish
• nbNO - Norwegian (Bokmål)
• ptBR - Portuguese (Brazil)
• svSE - Swedish

Resources (per LLD)

The calendar supports first-class resources and derives event color from the selected resource.

Types:

type CalendarResource = {
  id: string;
  name: string;
  accentClass?: string;
  color?: string;
  meta?: Record<string, unknown>;
};

Usage:

<EventCalendar
  events={events}
  resources={[
    { id: 'nurse-3', name: 'Nurse Casey', accentClass: 'border-l-2 border-amber-500' },
    { id: 'pi-1', name: 'Dr. Adams', accentClass: 'border-l-2 border-sky-500' },
  ]}
  // overlays optional
  onEventAdd={onAdd}
  onEventUpdate={onUpdate}
  onEventDelete={onDelete}
  onDateRangeChange={onRangeChange}
/>

Popup behavior:

• When resources are provided, the Event popup displays a Resource dropdown.
• Selecting a resource auto-sets the event color to the resource's color.
• Editing legacy events without resourceId will infer the resource by matching event.color to resource.color or resource.id.

## CSS Classes

The component uses the `ec-` prefix for all CSS classes to avoid conflicts with other libraries. Make sure to import the styles:

```tsx
import '@zealic/full-event-calendar/styles.css';

Development

Building

yarn build

Running Tests

yarn test

Linting

yarn lint

License

MIT License - see LICENSE.md for details.

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting pull requests.

Support

If you encounter any issues or have questions, please file an issue on our GitHub repository.