npm package: @masterteam/calendar
Description: Standalone Angular calendar component built on top of FullCalendar.
Latest version: 0.0.3

# @masterteam/calendar

Standalone Angular calendar component built on top of FullCalendar.

## Installation

Add the package and required peers in your workspace (Angular, FullCalendar, Transloco, and `@masterteam/components`).

## Exports

`@masterteam/calendar` exports:

- `Calendar` (standalone component)
- `CalendarEventMapping`
- `CalendarColorTransform`
- `CalendarEventTemplateDirective`
- `CalendarHeaderEndTemplateDirective`
- other related model types from `calendar.models.ts`

## Styles and i18n assets

Package exports:

- `@masterteam/calendar/assets/calendar.css`
- `@masterteam/calendar/assets/i18n/en.json`
- `@masterteam/calendar/assets/i18n/ar.json`

Include the CSS in your app styles and load i18n JSON files with your Transloco setup.

## Basic usage

```ts
import { Component, signal } from '@angular/core';
import { Calendar } from '@masterteam/calendar';

@Component({
  standalone: true,
  selector: 'app-demo',
  imports: [Calendar],
  template: `
    <mt-calendar
      [locale]="locale()"
      [data]="events()"
      [mapping]="mapping"
      [options]="options"
    />
  `,
})
export class DemoComponent {
  readonly locale = signal<'en' | 'ar'>('en');
  readonly events = signal([
    { uid: 'e-1', name: 'Kickoff', from: '2026-03-03', to: '2026-03-03' },
  ]);

  readonly mapping = {
    id: 'uid',
    title: 'name',
    dateFrom: 'from',
    dateTo: 'to',
  };

  readonly options = {
    eventClick: (arg: any) => {
      // FullCalendar EventClickArg
      console.log(arg.event.id, arg.event.extendedProps.__mtSource);
    },
  };
}
```

## Inputs

- `locale: 'en' | 'ar'` (default: `'en'`)
- `data: unknown[]` (default: `[]`)
- `mapping: CalendarEventMapping | null` (default: `null`)
- `colorTransform: CalendarColorTransform | null` (default: `null`)
- `options: Partial<CalendarOptions>` (default: `{}`)

### `mapping`

Use `mapping` to map your data shape into FullCalendar events:

- core fields: `id`, `title`, `dateFrom`, `dateTo`, `allDay`, `url`
- style fields: `backgroundColor`, `borderColor`, `textColor`, `classNames`
- behavior fields: `editable`, `startEditable`, `durationEditable`, `display`
- extras: `extendedProps`, `extendedPropsMap`, `time`

Each accessor can be:

- a dot-path string (example: `'meta.owner.id'`)
- a function `(item) => value`

The original source item is attached to event extended props as `__mtSource`.

### `colorTransform`

`colorTransform` lets you convert mapped color values to RGBA with alpha:

- `enabled`
- `alpha` (number or per-field config)
- `fields` (`backgroundColor`, `borderColor`, `textColor`)
- `invalidColorPolicy` (`keep` or `drop`)

## Event click contract

`options.eventClick` receives the standard FullCalendar `EventClickArg`.

- `arg.event` is the clicked event
- `arg.jsEvent.preventDefault()` is called by the calendar component
- source data is available at `arg.event.extendedProps.__mtSource`

## Template customization

### Event template

Use `ng-template[mtCalendarEvent]`:

```html
<mt-calendar [data]="events" [mapping]="mapping">
  <ng-template mtCalendarEvent let-source let-arg="arg">
    <div>{{ source?.title }} - {{ arg.event.start }}</div>
  </ng-template>
</mt-calendar>
```

Template context:

- `$implicit` / `source`: mapped source item or `null`
- `arg`: `EventContentArg`

### Header-end template

Use `ng-template[mtCalendarHeaderEnd]` (or `ng-template[mtHeaderEnd]`):

```html
<mt-calendar [data]="events">
  <ng-template mtCalendarHeaderEnd let-locale="locale" let-eventsCount="eventsCount">
    <div>{{ locale }} | {{ eventsCount }} events</div>
  </ng-template>
</mt-calendar>
```

Template context:

- `locale`
- `direction` (`ltr` or `rtl`)
- `eventsCount`

## Notes on options override

Some options are protected by the component and ignored if passed via `options`:

- `events`
- `locale`
- `locales`
- `plugins`
- `eventContent`
- `eventClick`
- `headerToolbar`