Calendar
API reference for @luxalgo/vela-pro-calendar, including the data source port, controller, widget, and event types.
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 | nullSee 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): CalendarWidgetSee also: CalendarProps, CalendarWidget.
emptyCalendar
function emptyCalendar(): CalendarDataSee 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): CalendarControllerSee also: CalendarController, EnableCalendarOptions.
formatFigure
A figure with its unit: 3.9%, -92.6B, 907M, 1.25.
function formatFigure(value: number | null, unit?: string | null): stringisSpeech
Speeches, testimonies and press conferences: events with a duration rather than a figure.
function isSpeech(name: string): booleanisWeekend
function isWeekend(dayKey: string): booleanitemsOn
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): CalendarStatusSee also: CalendarItem, CalendarStatus.
localDayKey
YYYY-MM-DD of an instant on the wall calendar of timeZone.
function localDayKey(ms: number, timeZone: string): stringnormalizeCalendar
function normalizeCalendar(data: Partial<CalendarData> | null | undefined): CalendarDataSee also: CalendarData.
refreshCalendars
Ask every mounted calendar bound to the module's controller to reload from its source.
function refreshCalendars(): voidsanitizeCalendarSettings
Untrusted persisted settings narrowed to valid values.
function sanitizeCalendarSettings(raw: unknown): CalendarSettingsSee 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): CalendarImpactSee also: CalendarImpact.
shiftDay
A day key moved by whole days.
function shiftDay(dayKey: string, days: number): stringsurprise
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' | nullsymbolOfItem
The symbol of a company event, or null for macro releases and market holidays.
function symbolOfItem(item: CalendarItem): string | nullSee also: CalendarItem.
timeZoneCity
Europe/Madrid → Madrid.
function timeZoneCity(timeZone: string): stringutcOffsetLabel
UTC+1, UTC−4, UTC+5:30, UTC.
function utcOffsetLabel(ms: number, timeZone: string): stringweekdayOf
0 = Sunday … 6 = Saturday.
function weekdayOf(dayKey: string): numberClasses
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;
}| 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, 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;
}| 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, CalendarSettings.
Interfaces and types
CalendarControllerOptions
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.
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;
}| 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, 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;
}| Member | Type | Description |
|---|---|---|
tab? | CalendarTab | Selected category tab. |
minImpact? | CalendarImpact | Minimum 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;
}| Member | Type | Description |
|---|---|---|
id | string | |
symbol | string | |
date | string | |
amount | number | |
yield? | number | null | Annual 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;
}| 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
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;
}| 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.
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;
}| 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, 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;
}| 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
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;