@localia/ngx-calendar-widget

A lightweight, customizable, and feature-rich Angular calendar widget designed to simplify event management and scheduling in your Angular applications.

Features

• Multi-locale support: Display calendar in different languages (English, Spanish, German, French, Italian)
• Customizable sizes: Choose between default, large, and extra-large sizes
• Event management: Add, display, and interact with events
• Responsive design: Works seamlessly across devices
• Easy integration: Simple to set up and use in Angular projects
• Flexible date handling: Use the default date-fns adapter or inject your own date library implementation

Installation

Install the library using npm:

npm install @localia/ngx-calendar-widget

Or with yarn:

yarn add @localia/ngx-calendar-widget

If you plan to use the default date adapter (based on date-fns), you'll need to install date-fns as well:

npm install @localia/ngx-calendar-widget date-fns

Or with yarn:

yarn add @localia/ngx-calendar-widget date-fns

Usage

Import the Module

Import the NgxCalendarWidgetModule into your Angular module:

import { NgxCalendarWidgetModule } from '@localia/ngx-calendar-widget';

@NgModule({
    imports: [
        // ...other imports
        NgxCalendarWidgetModule.forRoot() // Using default date-fns adapter
    ],
    // ...other module properties
})
export class AppModule {
}

Date Adapters

The calendar widget uses date adapters to handle date manipulations. By default, it uses date-fns, but you can provide your own implementation to use any date library of your choice (like Day.js, Moment.js, or others).

Using the Default date-fns Adapter

The default adapter is automatically configured when you use forRoot() without parameters:

import { NgxCalendarWidgetModule } from '@localia/ngx-calendar-widget';

@NgModule({
    imports: [
        NgxCalendarWidgetModule.forRoot() // Uses default date-fns adapter
    ],
    // ...
})
export class AppModule { }

Creating a Custom Date Adapter

To use a different date library, create a class that implements the DateAdapter interface:

import { DateAdapter } from '@localia/ngx-calendar-widget';
import * as dayjs from 'dayjs';
import * as weekOfYear from 'dayjs/plugin/weekOfYear';
import * as isSameOrBefore from 'dayjs/plugin/isSameOrBefore';
import * as isSameOrAfter from 'dayjs/plugin/isSameOrAfter';

// Initialize dayjs plugins
dayjs.extend(weekOfYear);
dayjs.extend(isSameOrBefore);
dayjs.extend(isSameOrAfter);

export class DayjsDateAdapter implements DateAdapter {
  getMonth(date: Date): number {
    return dayjs(date).month();
  }
  
  getYear(date: Date): number {
    return dayjs(date).year();
  }
  
  startOfWeek(date: Date, options?: { weekStartsOn: number }): Date {
    const weekStart = options?.weekStartsOn || 0;
    return dayjs(date).startOf('week').add(weekStart, 'day').toDate();
  }
  
  // Implement the rest of the methods from DateAdapter interface
  // ...
}

Using Your Custom Date Adapter

To use your custom adapter, provide it through the forRoot() method:

import { NgxCalendarWidgetModule, NgxCalendarWidgetConfigService, DATE_ADAPTER } from '@localia/ngx-calendar-widget';
import { DayjsDateAdapter } from './dayjs-date.adapter';

@NgModule({
    imports: [
        NgxCalendarWidgetModule.forRoot({
            dateAdapter: new DayjsDateAdapter()
        }),
    ],
    // or using providers via injecton token
    providers: [
        { provide: DATE_ADAPTER, useClass: DayjsDateAdapter }
    ]
    // ...
})
export class AppModule { }

Add to Template

Use the component in your template:

<ngx-calendar-widget
    [locale]="'en'"
    [size]="'default'"
    [events]="events"
    [enableAddEvent]="true"
    (addEvent)="onAddEvent($event)"
    (selectEvent)="onEventSelect($event)">
</ngx-calendar-widget>

Component Preview

Event Structure

Events must follow this interface:

interface CalendarEventInterface {
    id: number | string;     // Unique identifier for the event
    title: string;         // Event title to display on the calendar
    date: string;          // Start date/time in ISO format (YYYY-MM-DDTHH:mm:ss)
    endDate: string | null;  // End date/time in ISO format (optional)
}

Example Event Objects

// Single-day event
{
    id: 1, 
    title: "Team Meeting",
    date: "2023-10-15T14:00:00",
    endDate: "2023-10-15T15:30:00"
}

// Multi-day event
{
    id: "conf-2023",
    title: "Annual Conference",
    date: "2023-11-01T09:00:00",
    endDate: "2023-11-03T17:00:00"
}

// Event without end date (treated as single-day)
{
    id: 42,
    title: "Deadline",
    date: "2023-10-31T23:59:59",
    endDate: null
}

Component Inputs

Input	Type	Default	Description
locale	'en' | 'es'| 'de'| 'fr'| 'it'	'de'	Locale for the calendar.
size	'default'| 'large'| 'x-large'	'default'	Size of the calendar.
hideMultiDayEventsText	boolean	true	Hide text for multi-day events.
enableAddEvent	boolean	false	Enable the "Add Event" button.
events	CalendarEventInterface[]	[]	Array of events to display on the calendar.

Component Outputs

Output	Description
addEvent	Emits the date when the "Add Event" button is clicked.
clickEvent	Emits the event object when an event is clicked.

Handling Events

In your component, handle the emitted events:

import { Component } from '@angular/core';
import { CalendarEventInterface } from '@localia/ngx-calendar-widget';

@Component({
    selector: 'app-calendar-page',
    template: `
    <ngx-calendar-widget
      [events]="events"
      [enableAddEvent]="true"
      (addEvent)="onAddEvent($event)"
      (selectEvent)="onEventSelect($event)">
    </ngx-calendar-widget>
  `
})
export class CalendarPageComponent {
    events: CalendarEventInterface[] = [
        {
            id: 1,
            title: 'Team Meeting',
            date: '2023-10-01T10:00:00',
            endDate: '2023-10-01T12:00:00',
        },
        {
            id: 2,
            title: 'Conference',
            date: '2023-10-05T09:00:00',
            endDate: '2023-10-07T17:00:00',
        }
    ];

    onAddEvent(date: string) {
        console.log('Add event on:', date);
        // Implement your event creation logic here
    }

    onEventSelect(event: CalendarEventInterface) {
        console.log('Event clicked:', event);
        // Implement your event handling logic here
    }
}

Visual Appearance

The calendar displays events with different styles based on their duration:

• Single-day events: Displayed with start and end time
• Multi-day events:
  • First day shows the event title with full date range
  • Middle days can be configured to show or hide text (controlled by hideMultiDayEventsText)
  • Last day shows the event title with end date information

Building the Library

To build the library, run:

ng build @localia/ngx-calendar-widget

The build artifacts will be stored in the dist/@localia/ngx-calendar-widget directory.

Publishing the Library

To publish the library to npm:

1. Build the library:

   ng build @localia/ngx-calendar-widget

2. Navigate to the dist directory:

   cd dist/@localia/ngx-calendar-widget

3. Publish the library:

   npm publish --access public

Running Tests

Unit Tests

Run unit tests using Karma:

ng test

Browser Support

The widget is compatible with:

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Contributing

Contributions are welcome! If you find a bug or have a feature request, please open an issue or submit a pull request.

1. Fork the repository
2. Create your feature branch: git checkout -b feature/my-new-feature
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin feature/my-new-feature
5. Submit a pull request

License

This project is licensed under the MIT License.

Additional Resources

• Angular Documentation
• Date-fns Documentation (used for default date manipulations)

Credits

Developed by Localia

`