Vela, our next-generation charting platform, is live at vela.luxalgo.com.
LuxAlgo

Calendar

API reference for @luxalgo/vela-pro-calendar, including the data source port, controller, widget, and event types.

View as Markdown

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, Standalone widgets.

Functions

buildItems

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

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

See also: CalendarData, CalendarItem.

calendar

The market calendar as a Vela Pro plugin.

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

See also: CalendarController, EnableCalendarOptions, VelaProPlugin.

calendarController

The page's calendar controller, once enableCalendar or calendar() installed.

function calendarController(): CalendarController | null

See also: CalendarController.

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.

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

countsByDay

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

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

Default: minImpact = 'low'.

See also: CalendarImpact, CalendarItem, CalendarTab.

createCalendar

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

function createCalendar(props?: CalendarProps): CalendarWidget

See also: CalendarProps, CalendarWidget.

emptyCalendar

function emptyCalendar(): CalendarData

See also: CalendarData.

enableCalendar

Enable the CALENDAR side panel on every shell built afterwards. Returns the page's CalendarController. Call ONCE, before constructing shells. Idempotent.

function enableCalendar(opts?: EnableCalendarOptions): CalendarController

See also: CalendarController, EnableCalendarOptions.

formatFigure

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

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

isSpeech

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

function isSpeech(name: string): boolean

isWeekend

function isWeekend(dayKey: string): boolean

itemsOn

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

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

Default: minImpact = 'low'.

See also: CalendarImpact, CalendarItem, CalendarTab.

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.

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

See also: CalendarItem, CalendarStatus.

localDayKey

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

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

normalizeCalendar

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

See also: CalendarData.

refreshCalendars

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

function refreshCalendars(): void

sanitizeCalendarSettings

Untrusted persisted settings narrowed to valid values.

function sanitizeCalendarSettings(raw: unknown): CalendarSettings

See also: CalendarSettings.

sanitizeCalendarTabs

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

function sanitizeCalendarTabs(tabs: unknown): CalendarTab[]

See also: CalendarTab.

sanitizeImpact

A valid impact threshold, or 'low'.

function sanitizeImpact(impact: unknown): CalendarImpact

See also: CalendarImpact.

shiftDay

A day key moved by whole days.

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

surprise

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

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

symbolOfItem

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

function symbolOfItem(item: CalendarItem): string | null

See also: CalendarItem.

timeZoneCity

Europe/Madrid → Madrid.

function timeZoneCity(timeZone: string): string

utcOffsetLabel

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

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

weekdayOf

0 = Sunday … 6 = Saturday.

function weekdayOf(dayKey: string): number

Classes

CalendarController class

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;
}
MemberTypeDescription
constructor(opts?: CalendarControllerOptions)
hasSourceboolean
sourceCalendarSource | null
setSource()(source: CalendarSource | null | undefined) => voidConnect or swap the calendar data source, dropping cached windows.
refresh()() => voidDrop cached windows so open widgets ask the source again.
onChange()(listener: () => void) => () => voidSubscribe to source changes, completed loads and refreshes.
read()(range: { from: string; to: string }) => CalendarRangeStateRead range's cached state, starting its load when needed.
reload()(range: { from: string; to: string }) => voidRetry a range that failed (or reload a specific range).
destroy()() => void

See also: CalendarControllerOptions, CalendarRangeState, CalendarSource.

CalendarWidget

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;
}
MemberTypeDescription
constructor(props?: CalendarProps)
elHTMLElement
toolsHTMLElementCompact 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()() => CalendarSettingsWhat the user picked, for a host to persist.
applySettings()(s: CalendarSettings) => voidApply persisted settings.
refresh()() => voidDrop cached windows and ask the source again.
destroy()() => void

See also: CalendarProps, CalendarSettings.

Interfaces and types

CalendarControllerOptions

interface CalendarControllerOptions {
    source?: CalendarSource | null;
}
MemberTypeDescription
source?CalendarSource | nullWhere the calendar's items come from. Without one, hasSource is false.

See also: CalendarSource.

CalendarData

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

See also: DividendEvent, EarningsReport, EconomicRelease, IpoEvent, MarketHoliday, SplitEvent.

CalendarImpact

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

CalendarItem

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, EarningsReport, EconomicRelease, IpoEvent, MarketHoliday, SplitEvent.

CalendarProps

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

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;
}
MemberTypeDescription
controller?CalendarControllerShared calendar state; optional when source is given directly.
source?CalendarSource | nullCalendar data port when no controller is passed.
symbol?stringActive symbol, used to highlight matching company events.
timeZone?stringViewer's IANA time zone (default: the browser's).
tabs?readonly CalendarTab[]Category tabs shown, in order (default all six).
minImpact?CalendarImpactHide economic releases below this impact (default 'low': show all).
settings?CalendarSettingsInitial persisted settings (tab, minImpact).
now?() => numberClock function for deterministic tests (default Date.now).
host?HTMLElementWhere menus mount (default: the widget's own element).
active?booleanLoad and tick while shown (default true).
onSelectSymbol?(symbol: string) => voidCalled when the user clicks a company event (earnings, dividends, splits, ipos).
onItemClick?(item: CalendarItem) => voidCalled when the user clicks any item row.
onSettingsChange?(settings: CalendarSettings) => voidCalled when the user changes tab or minImpact.

See also: CalendarController, CalendarImpact, CalendarItem, CalendarSettings, CalendarSource, CalendarTab.

CalendarRangeState

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

See also: CalendarData.

CalendarSettings

Calendar settings a host keeps between sessions.

interface CalendarSettings {
    tab?: CalendarTab;
    minImpact?: CalendarImpact;
}
MemberTypeDescription
tab?CalendarTabSelected category tab.
minImpact?CalendarImpactMinimum impact shown on the Economic tab.

See also: CalendarImpact, CalendarTab.

CalendarSource

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

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

See also: CalendarData.

CalendarStatus

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

CalendarTab

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

DividendEvent

A dividend on its ex-dividend date.

interface DividendEvent {
    id: string;
    symbol: string;
    date: string;
    amount: number;
    yield?: number | null;
    paymentDate?: string | null;
}
MemberTypeDescription
idstring
symbolstring
datestring
amountnumber
yield?number | nullAnnual yield, percent.
paymentDate?string | null

EarningsReport

A company's earnings on its report date.

interface EarningsReport {
    id: string;
    symbol: string;
    date: string;
    hour?: 'bmo' | 'amc' | null;
    epsActual: number | null;
    epsEstimate: number | null;
    revenueActual: number | null;
    revenueEstimate: number | null;
}
MemberTypeDescription
idstring
symbolstring
datestringYYYY-MM-DD.
hour?'bmo' | 'amc' | nullbmo before the open, amc after the close.
epsActualnumber | null
epsEstimatenumber | null
revenueActualnumber | null
revenueEstimatenumber | null

EconomicRelease

One economic release.

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;
}
MemberTypeDescription
idstring
atnumberRelease instant, epoch ms.
countrystringISO-3166 country (US, EU, JP).
currencystringThe currency the release moves (USD).
eventstring
period?string | nullWhat the figure covers (Sep, Q3, Oct/24).
impactCalendarImpact
previousnumber | null
forecastnumber | null
actualnumber | nullNull until the figure is out.
unit?string | null%, K, M, B, T, or a free suffix.

See also: CalendarImpact.

EnableCalendarOptions

Options for enableCalendar and calendar.

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;
}
MemberTypeDescription
source?CalendarSource | nullWhere calendar items come from; without one the panel shows an empty state.
timeZone?stringViewer's IANA time zone (default: the browser's).
tabs?readonly CalendarTab[]Category tabs shown, in order (default all six).
minImpact?CalendarImpactInitial minimum impact on the Economic tab (default 'low'; user choices persist over it).
settings?CalendarSettingsInitial settings (tab, minImpact); user choices persist over them.
selectSymbol?booleanClicking a company event opens its symbol on the chart (default true).
onItemClick?(item: CalendarItem, ctx: WidgetContext) => voidCalled when any item row is clicked.
width?number
order?numberPlace among the sidebar panel buttons (default 5).

See also: CalendarImpact, CalendarItem, CalendarSettings, CalendarSource, CalendarTab. From @luxalgo/vela/plugin: WidgetContext.

IpoEvent

An expected listing.

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

MarketHoliday

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

interface MarketHoliday {
    id: string;
    date: string;
    market: string;
    name: string;
    earlyClose?: string | null;
}
MemberTypeDescription
idstring
datestring
marketstring
namestring
earlyClose?string | null13:00 when the market closes early instead of staying shut.

SplitEvent

A split on its effective date.

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

Constants

CALENDAR_IMPACTS

const CALENDAR_IMPACTS: readonly CalendarImpact[];

See also: CalendarImpact.

CALENDAR_PANEL_ID

const CALENDAR_PANEL_ID: 'vela-pro.calendar';

CALENDAR_TABS

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

See also: CalendarTab.

SPEECH_LIVE_MINUTES

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

const SPEECH_LIVE_MINUTES: 45;

On this page