# Calendar (/vela-pro/api/calendar)



This page documents `@luxalgo/vela-pro-calendar`, including the `calendar()` plugin factory, `CalendarSource` port, `CalendarController`, standalone calendar widget, and economic and corporate event types.

Import symbols on this page from `@luxalgo/vela-pro-calendar`. Related guides: [Calendar](/vela-pro/modules/catalog/calendar), [Standalone widgets](/vela-pro/modules/widgets).

## Functions [#functions]

### `buildItems` [#builditems]

Everything the source sent, as items on the viewer's days.

```typescript
function buildItems(data: CalendarData, timeZone: string): CalendarItem[]
```

See also: [`CalendarData`](/vela-pro/api/calendar#calendardata), [`CalendarItem`](/vela-pro/api/calendar#calendaritem).

### `calendar` [#calendar]

The market calendar as a Vela Pro plugin.

```typescript
function calendar(opts?: EnableCalendarOptions): VelaProPlugin<CalendarController>
```

See also: [`CalendarController`](/vela-pro/api/calendar#calendarcontroller-class), [`EnableCalendarOptions`](/vela-pro/api/calendar#enablecalendaroptions), [`VelaProPlugin`](/vela-pro/api/module-sdk#velaproplugin).

### `calendarController` [#calendarcontroller]

The page's calendar controller, once [`enableCalendar`](/vela-pro/api/calendar#enablecalendar) or [`calendar()`](/vela-pro/api/calendar#calendar) installed.

```typescript
function calendarController(): CalendarController | null
```

See also: [`CalendarController`](/vela-pro/api/calendar#calendarcontroller-class).

### `calendarWindow` [#calendarwindow]

The days the panel can show and the range it loads: from the Monday of last week, four whole weeks, so every day of a week asks the source for the same range.

```typescript
function calendarWindow(todayKey: string): { from: string; to: string; days: string[] }
```

### `countsByDay` [#countsbyday]

How many items a tab has on each day, for the day strip's dots.

```typescript
function countsByDay(
    items: readonly CalendarItem[],
    tab: CalendarTab,
    minImpact?: CalendarImpact,
): Map<string, number>
```

Default: `minImpact = 'low'`.

See also: [`CalendarImpact`](/vela-pro/api/calendar#calendarimpact), [`CalendarItem`](/vela-pro/api/calendar#calendaritem), [`CalendarTab`](/vela-pro/api/calendar#calendartab).

### `createCalendar` [#createcalendar]

The market calendar as a widget: `{ el, tools, update, destroy }`.

```typescript
function createCalendar(props?: CalendarProps): CalendarWidget
```

See also: [`CalendarProps`](/vela-pro/api/calendar#calendarprops), [`CalendarWidget`](/vela-pro/api/calendar#calendarwidget).

### `emptyCalendar` [#emptycalendar]

```typescript
function emptyCalendar(): CalendarData
```

See also: [`CalendarData`](/vela-pro/api/calendar#calendardata).

### `enableCalendar` [#enablecalendar]

Enable the CALENDAR side panel on every shell built afterwards. Returns the page's [`CalendarController`](/vela-pro/api/calendar#calendarcontroller-class). Call ONCE, before constructing shells. Idempotent.

```typescript
function enableCalendar(opts?: EnableCalendarOptions): CalendarController
```

See also: [`CalendarController`](/vela-pro/api/calendar#calendarcontroller-class), [`EnableCalendarOptions`](/vela-pro/api/calendar#enablecalendaroptions).

### `formatFigure` [#formatfigure]

A figure with its unit: `3.9%`, `-92.6B`, `907M`, `1.25`.

```typescript
function formatFigure(value: number | null, unit?: string | null): string
```

### `isSpeech` [#isspeech]

Speeches, testimonies and press conferences: events with a duration rather than a figure.

```typescript
function isSpeech(name: string): boolean
```

### `isWeekend` [#isweekend]

```typescript
function isWeekend(dayKey: string): boolean
```

### `itemsOn` [#itemson]

A tab's items on one day: releases by time (then impact), company events by symbol.

```typescript
function itemsOn(
    items: readonly CalendarItem[],
    tab: CalendarTab,
    day: string,
    minImpact?: CalendarImpact,
): CalendarItem[]
```

Default: `minImpact = 'low'`.

See also: [`CalendarImpact`](/vela-pro/api/calendar#calendarimpact), [`CalendarItem`](/vela-pro/api/calendar#calendaritem), [`CalendarTab`](/vela-pro/api/calendar#calendartab).

### `itemStatus` [#itemstatus]

Whether an item has happened, as of `now`: a release is `released` once its figure is in and `awaiting` between its time and its figure; a speech is `live` for its first minutes; an earnings report once reported; any other dated event once its day has passed.

```typescript
function itemStatus(item: CalendarItem, now: number, todayKey: string): CalendarStatus
```

See also: [`CalendarItem`](/vela-pro/api/calendar#calendaritem), [`CalendarStatus`](/vela-pro/api/calendar#calendarstatus).

### `localDayKey` [#localdaykey]

`YYYY-MM-DD` of an instant on the wall calendar of `timeZone`.

```typescript
function localDayKey(ms: number, timeZone: string): string
```

### `normalizeCalendar` [#normalizecalendar]

```typescript
function normalizeCalendar(data: Partial<CalendarData> | null | undefined): CalendarData
```

See also: [`CalendarData`](/vela-pro/api/calendar#calendardata).

### `refreshCalendars` [#refreshcalendars]

Ask every mounted calendar bound to the module's controller to reload from its source.

```typescript
function refreshCalendars(): void
```

### `sanitizeCalendarSettings` [#sanitizecalendarsettings]

Untrusted persisted settings narrowed to valid values.

```typescript
function sanitizeCalendarSettings(raw: unknown): CalendarSettings
```

See also: [`CalendarSettings`](/vela-pro/api/calendar#calendarsettings).

### `sanitizeCalendarTabs` [#sanitizecalendartabs]

Known tab ids once each, or all six when none survive.

```typescript
function sanitizeCalendarTabs(tabs: unknown): CalendarTab[]
```

See also: [`CalendarTab`](/vela-pro/api/calendar#calendartab).

### `sanitizeImpact` [#sanitizeimpact]

A valid impact threshold, or `'low'`.

```typescript
function sanitizeImpact(impact: unknown): CalendarImpact
```

See also: [`CalendarImpact`](/vela-pro/api/calendar#calendarimpact).

### `shiftDay` [#shiftday]

A day key moved by whole days.

```typescript
function shiftDay(dayKey: string, days: number): string
```

### `surprise` [#surprise]

Up when `value` beats `reference`, down when it misses; null when either is missing or they tie.

```typescript
function surprise(value: number | null, reference: number | null): 'up' | 'down' | null
```

### `symbolOfItem` [#symbolofitem]

The symbol of a company event, or null for macro releases and market holidays.

```typescript
function symbolOfItem(item: CalendarItem): string | null
```

See also: [`CalendarItem`](/vela-pro/api/calendar#calendaritem).

### `timeZoneCity` [#timezonecity]

`Europe/Madrid` → `Madrid`.

```typescript
function timeZoneCity(timeZone: string): string
```

### `utcOffsetLabel` [#utcoffsetlabel]

`UTC+1`, `UTC−4`, `UTC+5:30`, `UTC`.

```typescript
function utcOffsetLabel(ms: number, timeZone: string): string
```

### `weekdayOf` [#weekdayof]

0 = Sunday … 6 = Saturday.

```typescript
function weekdayOf(dayKey: string): number
```

## Classes [#classes]

### `CalendarController` class [#calendarcontroller-class]

```typescript
class CalendarController {
    constructor(opts?: CalendarControllerOptions);
    readonly hasSource: boolean;
    readonly source: CalendarSource | null;
    setSource(source: CalendarSource | null | undefined): void;
    refresh(): void;
    onChange(listener: () => void): () => void;
    read(range: { from: string; to: string }): CalendarRangeState;
    reload(range: { from: string; to: string }): void;
    destroy(): void;
}
```

| Member        | Type                                                          | Description                                                        |
| ------------- | ------------------------------------------------------------- | ------------------------------------------------------------------ |
| `constructor` | `(opts?: CalendarControllerOptions)`                          |                                                                    |
| `hasSource`   | `boolean`                                                     |                                                                    |
| `source`      | `CalendarSource \| null`                                      |                                                                    |
| `setSource()` | `(source: CalendarSource \| null \| undefined) => void`       | Connect or swap the calendar data source, dropping cached windows. |
| `refresh()`   | `() => void`                                                  | Drop cached windows so open widgets ask the source again.          |
| `onChange()`  | `(listener: () => void) => () => void`                        | Subscribe to source changes, completed loads and refreshes.        |
| `read()`      | `(range: { from: string; to: string }) => CalendarRangeState` | Read `range`'s cached state, starting its load when needed.        |
| `reload()`    | `(range: { from: string; to: string }) => void`               | Retry a range that failed (or reload a specific range).            |
| `destroy()`   | `() => void`                                                  |                                                                    |

See also: [`CalendarControllerOptions`](/vela-pro/api/calendar#calendarcontrolleroptions), [`CalendarRangeState`](/vela-pro/api/calendar#calendarrangestate), [`CalendarSource`](/vela-pro/api/calendar#calendarsource).

### `CalendarWidget` [#calendarwidget]

```typescript
class CalendarWidget {
    constructor(props?: CalendarProps);
    readonly el: HTMLElement;
    readonly tools: HTMLElement;
    update(next: Partial<Omit<CalendarProps, 'controller' | 'tabs'>>): void;
    settings(): CalendarSettings;
    applySettings(s: CalendarSettings): void;
    refresh(): void;
    destroy(): void;
}
```

| Member            | Type                                                                   | Description                                                                                          |
| ----------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `constructor`     | `(props?: CalendarProps)`                                              |                                                                                                      |
| `el`              | `HTMLElement`                                                          |                                                                                                      |
| `tools`           | `HTMLElement`                                                          | Compact controls (impact filter, refresh): in the widget's top row until lifted into a panel header. |
| `update()`        | `(next: Partial<Omit<CalendarProps, 'controller' \| 'tabs'>>) => void` |                                                                                                      |
| `settings()`      | `() => CalendarSettings`                                               | What the user picked, for a host to persist.                                                         |
| `applySettings()` | `(s: CalendarSettings) => void`                                        | Apply persisted settings.                                                                            |
| `refresh()`       | `() => void`                                                           | Drop cached windows and ask the source again.                                                        |
| `destroy()`       | `() => void`                                                           |                                                                                                      |

See also: [`CalendarProps`](/vela-pro/api/calendar#calendarprops), [`CalendarSettings`](/vela-pro/api/calendar#calendarsettings).

## Interfaces and types [#interfaces-and-types]

### `CalendarControllerOptions` [#calendarcontrolleroptions]

```typescript
interface CalendarControllerOptions {
    source?: CalendarSource | null;
}
```

| Member    | Type                     | Description                                                              |
| --------- | ------------------------ | ------------------------------------------------------------------------ |
| `source?` | `CalendarSource \| null` | Where the calendar's items come from. Without one, `hasSource` is false. |

See also: [`CalendarSource`](/vela-pro/api/calendar#calendarsource).

### `CalendarData` [#calendardata]

```typescript
interface CalendarData {
    economic: EconomicRelease[];
    earnings: EarningsReport[];
    dividends: DividendEvent[];
    splits: SplitEvent[];
    ipos: IpoEvent[];
    holidays: MarketHoliday[];
}
```

See also: [`DividendEvent`](/vela-pro/api/calendar#dividendevent), [`EarningsReport`](/vela-pro/api/calendar#earningsreport), [`EconomicRelease`](/vela-pro/api/calendar#economicrelease), [`IpoEvent`](/vela-pro/api/calendar#ipoevent), [`MarketHoliday`](/vela-pro/api/calendar#marketholiday), [`SplitEvent`](/vela-pro/api/calendar#splitevent).

### `CalendarImpact` [#calendarimpact]

```typescript
type CalendarImpact = 'high' | 'medium' | 'low';
```

### `CalendarItem` [#calendaritem]

```typescript
type CalendarItem =
    | { kind: 'economic'; id: string; day: string; at: number; event: EconomicRelease }
    | { kind: 'earnings'; id: string; day: string; at: null; event: EarningsReport }
    | { kind: 'dividends'; id: string; day: string; at: null; event: DividendEvent }
    | { kind: 'splits'; id: string; day: string; at: null; event: SplitEvent }
    | { kind: 'ipos'; id: string; day: string; at: null; event: IpoEvent }
    | { kind: 'holidays'; id: string; day: string; at: null; event: MarketHoliday };
```

See also: [`DividendEvent`](/vela-pro/api/calendar#dividendevent), [`EarningsReport`](/vela-pro/api/calendar#earningsreport), [`EconomicRelease`](/vela-pro/api/calendar#economicrelease), [`IpoEvent`](/vela-pro/api/calendar#ipoevent), [`MarketHoliday`](/vela-pro/api/calendar#marketholiday), [`SplitEvent`](/vela-pro/api/calendar#splitevent).

### `CalendarProps` [#calendarprops]

The calendar widget's props. `tabs` is read once; the others can change through `update`.

```typescript
interface CalendarProps {
    controller?: CalendarController;
    source?: CalendarSource | null;
    symbol?: string;
    timeZone?: string;
    tabs?: readonly CalendarTab[];
    minImpact?: CalendarImpact;
    settings?: CalendarSettings;
    now?: () => number;
    host?: HTMLElement;
    active?: boolean;
    onSelectSymbol?: (symbol: string) => void;
    onItemClick?: (item: CalendarItem) => void;
    onSettingsChange?: (settings: CalendarSettings) => void;
}
```

| Member              | Type                                   | Description                                                                              |
| ------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------- |
| `controller?`       | `CalendarController`                   | Shared calendar state; optional when `source` is given directly.                         |
| `source?`           | `CalendarSource \| null`               | Calendar data port when no `controller` is passed.                                       |
| `symbol?`           | `string`                               | Active symbol, used to highlight matching company events.                                |
| `timeZone?`         | `string`                               | Viewer's IANA time zone (default: the browser's).                                        |
| `tabs?`             | `readonly CalendarTab[]`               | Category tabs shown, in order (default all six).                                         |
| `minImpact?`        | `CalendarImpact`                       | Hide economic releases below this impact (default `'low'`: show all).                    |
| `settings?`         | `CalendarSettings`                     | Initial persisted settings (`tab`, `minImpact`).                                         |
| `now?`              | `() => number`                         | Clock function for deterministic tests (default `Date.now`).                             |
| `host?`             | `HTMLElement`                          | Where menus mount (default: the widget's own element).                                   |
| `active?`           | `boolean`                              | Load and tick while shown (default `true`).                                              |
| `onSelectSymbol?`   | `(symbol: string) => void`             | Called when the user clicks a company event (`earnings`, `dividends`, `splits`, `ipos`). |
| `onItemClick?`      | `(item: CalendarItem) => void`         | Called when the user clicks any item row.                                                |
| `onSettingsChange?` | `(settings: CalendarSettings) => void` | Called when the user changes `tab` or `minImpact`.                                       |

See also: [`CalendarController`](/vela-pro/api/calendar#calendarcontroller-class), [`CalendarImpact`](/vela-pro/api/calendar#calendarimpact), [`CalendarItem`](/vela-pro/api/calendar#calendaritem), [`CalendarSettings`](/vela-pro/api/calendar#calendarsettings), [`CalendarSource`](/vela-pro/api/calendar#calendarsource), [`CalendarTab`](/vela-pro/api/calendar#calendartab).

### `CalendarRangeState` [#calendarrangestate]

```typescript
type CalendarRangeState =
    | { readonly state: 'idle' }
    | { readonly state: 'loading' }
    | { readonly state: 'ready'; readonly data: CalendarData }
    | { readonly state: 'error'; readonly message: string };
```

See also: [`CalendarData`](/vela-pro/api/calendar#calendardata).

### `CalendarSettings` [#calendarsettings]

Calendar settings a host keeps between sessions.

```typescript
interface CalendarSettings {
    tab?: CalendarTab;
    minImpact?: CalendarImpact;
}
```

| Member       | Type             | Description                               |
| ------------ | ---------------- | ----------------------------------------- |
| `tab?`       | `CalendarTab`    | Selected category tab.                    |
| `minImpact?` | `CalendarImpact` | Minimum impact shown on the Economic tab. |

See also: [`CalendarImpact`](/vela-pro/api/calendar#calendarimpact), [`CalendarTab`](/vela-pro/api/calendar#calendartab).

### `CalendarSource` [#calendarsource]

Where the calendar's items come from: the host's port. Missing sections read as empty.

```typescript
interface CalendarSource {
    load(range: { from: string; to: string }, signal: AbortSignal): Promise<Partial<CalendarData>>;
}
```

See also: [`CalendarData`](/vela-pro/api/calendar#calendardata).

### `CalendarStatus` [#calendarstatus]

```typescript
type CalendarStatus = 'upcoming' | 'live' | 'released' | 'awaiting';
```

### `CalendarTab` [#calendartab]

```typescript
type CalendarTab = 'economic' | 'earnings' | 'dividends' | 'splits' | 'ipos' | 'holidays';
```

### `DividendEvent` [#dividendevent]

A dividend on its ex-dividend date.

```typescript
interface DividendEvent {
    id: string;
    symbol: string;
    date: string;
    amount: number;
    yield?: number | null;
    paymentDate?: string | null;
}
```

| Member         | Type             | Description            |
| -------------- | ---------------- | ---------------------- |
| `id`           | `string`         |                        |
| `symbol`       | `string`         |                        |
| `date`         | `string`         |                        |
| `amount`       | `number`         |                        |
| `yield?`       | `number \| null` | Annual yield, percent. |
| `paymentDate?` | `string \| null` |                        |

### `EarningsReport` [#earningsreport]

A company's earnings on its report date.

```typescript
interface EarningsReport {
    id: string;
    symbol: string;
    date: string;
    hour?: 'bmo' | 'amc' | null;
    epsActual: number | null;
    epsEstimate: number | null;
    revenueActual: number | null;
    revenueEstimate: number | null;
}
```

| Member            | Type                     | Description                                   |
| ----------------- | ------------------------ | --------------------------------------------- |
| `id`              | `string`                 |                                               |
| `symbol`          | `string`                 |                                               |
| `date`            | `string`                 | `YYYY-MM-DD`.                                 |
| `hour?`           | `'bmo' \| 'amc' \| null` | `bmo` before the open, `amc` after the close. |
| `epsActual`       | `number \| null`         |                                               |
| `epsEstimate`     | `number \| null`         |                                               |
| `revenueActual`   | `number \| null`         |                                               |
| `revenueEstimate` | `number \| null`         |                                               |

### `EconomicRelease` [#economicrelease]

One economic release.

```typescript
interface EconomicRelease {
    id: string;
    at: number;
    country: string;
    currency: string;
    event: string;
    period?: string | null;
    impact: CalendarImpact;
    previous: number | null;
    forecast: number | null;
    actual: number | null;
    unit?: string | null;
}
```

| Member     | Type             | Description                                     |
| ---------- | ---------------- | ----------------------------------------------- |
| `id`       | `string`         |                                                 |
| `at`       | `number`         | Release instant, epoch ms.                      |
| `country`  | `string`         | ISO-3166 country (`US`, `EU`, `JP`).            |
| `currency` | `string`         | The currency the release moves (`USD`).         |
| `event`    | `string`         |                                                 |
| `period?`  | `string \| null` | What the figure covers (`Sep`, `Q3`, `Oct/24`). |
| `impact`   | `CalendarImpact` |                                                 |
| `previous` | `number \| null` |                                                 |
| `forecast` | `number \| null` |                                                 |
| `actual`   | `number \| null` | Null until the figure is out.                   |
| `unit?`    | `string \| null` | `%`, `K`, `M`, `B`, `T`, or a free suffix.      |

See also: [`CalendarImpact`](/vela-pro/api/calendar#calendarimpact).

### `EnableCalendarOptions` [#enablecalendaroptions]

Options for [`enableCalendar`](/vela-pro/api/calendar#enablecalendar) and `calendar`.

```typescript
interface EnableCalendarOptions {
    source?: CalendarSource | null;
    timeZone?: string;
    tabs?: readonly CalendarTab[];
    minImpact?: CalendarImpact;
    settings?: CalendarSettings;
    selectSymbol?: boolean;
    onItemClick?: (item: CalendarItem, ctx: WidgetContext) => void;
    width?: number;
    order?: number;
}
```

| Member          | Type                                               | Description                                                                                 |
| --------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `source?`       | `CalendarSource \| null`                           | Where calendar items come from; without one the panel shows an empty state.                 |
| `timeZone?`     | `string`                                           | Viewer's IANA time zone (default: the browser's).                                           |
| `tabs?`         | `readonly CalendarTab[]`                           | Category tabs shown, in order (default all six).                                            |
| `minImpact?`    | `CalendarImpact`                                   | Initial minimum impact on the Economic tab (default `'low'`; user choices persist over it). |
| `settings?`     | `CalendarSettings`                                 | Initial settings (`tab`, `minImpact`); user choices persist over them.                      |
| `selectSymbol?` | `boolean`                                          | Clicking a company event opens its symbol on the chart (default `true`).                    |
| `onItemClick?`  | `(item: CalendarItem, ctx: WidgetContext) => void` | Called when any item row is clicked.                                                        |
| `width?`        | `number`                                           |                                                                                             |
| `order?`        | `number`                                           | Place among the sidebar panel buttons (default 5).                                          |

See also: [`CalendarImpact`](/vela-pro/api/calendar#calendarimpact), [`CalendarItem`](/vela-pro/api/calendar#calendaritem), [`CalendarSettings`](/vela-pro/api/calendar#calendarsettings), [`CalendarSource`](/vela-pro/api/calendar#calendarsource), [`CalendarTab`](/vela-pro/api/calendar#calendartab). From `@luxalgo/vela/plugin`: `WidgetContext`.

### `IpoEvent` [#ipoevent]

An expected listing.

```typescript
interface IpoEvent {
    id: string;
    symbol: string;
    date: string;
    company?: string | null;
    exchange?: string | null;
    priceRange?: string | null;
    shares?: number | null;
}
```

### `MarketHoliday` [#marketholiday]

A market closed (or closing early) for the day.

```typescript
interface MarketHoliday {
    id: string;
    date: string;
    market: string;
    name: string;
    earlyClose?: string | null;
}
```

| Member        | Type             | Description                                                   |
| ------------- | ---------------- | ------------------------------------------------------------- |
| `id`          | `string`         |                                                               |
| `date`        | `string`         |                                                               |
| `market`      | `string`         |                                                               |
| `name`        | `string`         |                                                               |
| `earlyClose?` | `string \| null` | `13:00` when the market closes early instead of staying shut. |

### `SplitEvent` [#splitevent]

A split on its effective date.

```typescript
interface SplitEvent {
    id: string;
    symbol: string;
    date: string;
    numerator: number;
    denominator: number;
}
```

## Constants [#constants]

### `CALENDAR_IMPACTS` [#calendar_impacts]

```typescript
const CALENDAR_IMPACTS: readonly CalendarImpact[];
```

See also: [`CalendarImpact`](/vela-pro/api/calendar#calendarimpact).

### `CALENDAR_PANEL_ID` [#calendar_panel_id]

```typescript
const CALENDAR_PANEL_ID: 'vela-pro.calendar';
```

### `CALENDAR_TABS` [#calendar_tabs]

```typescript
const CALENDAR_TABS: ReadonlyArray<{ id: CalendarTab; label: string }>;
```

See also: [`CalendarTab`](/vela-pro/api/calendar#calendartab).

### `SPEECH_LIVE_MINUTES` [#speech_live_minutes]

How long a speech or press conference reads as live after its start.

```typescript
const SPEECH_LIVE_MINUTES: 45;
```
