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

Watchlist

API reference for @luxalgo/vela-pro-watchlist, including the watchlist plugin, controller, widgets, and storage port.

View as Markdown

This page documents @luxalgo/vela-pro-watchlist, including the watchlist() plugin factory, WatchlistController, standalone watchlist and symbol detail widgets, and the watchlist storage port.

Import symbols on this page from @luxalgo/vela-pro-watchlist. Related guides: Watchlist, Standalone widgets.

Functions

createWatchlist

The watchlist as a widget: { el, tools, update, openAdd, destroy }.

function createWatchlist(props: WatchlistProps): WatchlistWidget

See also: WatchlistProps, WatchlistWidget.

createWatchlistView

The full view as a widget: { el, update, destroy }.

function createWatchlistView(props: WatchlistViewProps): WatchlistViewWidget

See also: WatchlistViewProps, WatchlistViewWidget.

enableWatchlist

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

function enableWatchlist(opts?: EnableWatchlistOptions): WatchlistController

See also: EnableWatchlistOptions, WatchlistController.

watchlist

The watchlist as a Vela Pro plugin. With alerts on, a row's menu can create an alert.

function watchlist(opts?: EnableWatchlistOptions): VelaProPlugin<WatchlistController>

See also: EnableWatchlistOptions, VelaProPlugin, WatchlistController.

watchlistController

function watchlistController(): WatchlistController | null

See also: WatchlistController.

watchlistLayout

The row layout for a panel width px wide: Last, Chg and Chg% stay whatever the width and a narrower panel tightens the row instead; only Volume gives way when even the tightest row has no room for it.

function watchlistLayout(
    chosen: Record<WatchlistColumnId, boolean>,
    width: number | null,
): WatchlistLayout

// Unexported supporting types referenced above
interface WatchlistLayout {
    density: WatchlistDensity;
    columns: Record<WatchlistColumnId, boolean>;
    widths: Record<WatchlistColumnId, number>;
}
type WatchlistDensity = 'roomy' | 'regular' | 'compact';

See also: WatchlistColumnId.

Classes

LocalWatchlistStorage

class LocalWatchlistStorage implements WatchlistStorage {
    constructor(key?: string);
    load(): WatchlistState | null;
    save(state: WatchlistState): void;
}

Default: constructor(key = 'velapro.watchlists').

See also: WatchlistState, WatchlistStorage.

MemoryWatchlistStorage

class MemoryWatchlistStorage implements WatchlistStorage {
    constructor(seed?: WatchlistState | null);
    load(): WatchlistState | null;
    save(state: WatchlistState): void;
}

Default: constructor(seed = null).

See also: WatchlistState, WatchlistStorage.

WatchlistController class

class WatchlistController {
    constructor(opts: WatchlistControllerOptions);
    readonly ready: Promise<void>;
    state(): WatchlistState;
    onChange(cb: (s: WatchlistState) => void): () => void;
    update(op: (s: WatchlistState) => WatchlistState): void;
    seedIfEmpty(seed?: () => WatchlistEntry[]): Promise<boolean>;
    add(symbol: string): void;
    remove(symbol: string): void;
    has(symbol: string): boolean;
}
MemberTypeDescription
constructor(opts: WatchlistControllerOptions)
readyPromise<void>Resolves once storage answered (an async backend).
state()() => WatchlistState
onChange()(cb: (s: WatchlistState) => void) => () => void
update()(op: (s: WatchlistState) => WatchlistState) => voidApply a pure operation from ./model (or any state → state function).
seedIfEmpty()(seed?: () => WatchlistEntry[]) => Promise<boolean>Fill an empty first list from the seed: after storage answered, so a kept state is never overwritten. Resolves false while the seed has nothing yet (ask again later).
add()(symbol: string) => void
remove()(symbol: string) => void
has()(symbol: string) => boolean

See also: WatchlistControllerOptions, WatchlistEntry, WatchlistState.

WatchlistViewWidget

class WatchlistViewWidget {
    constructor(props: WatchlistViewProps);
    readonly el: HTMLElement;
    update(next: Partial<Omit<WatchlistViewProps, 'controller' | 'quotes'>>): void;
    destroy(): void;
}

See also: WatchlistViewProps.

WatchlistWidget

class WatchlistWidget {
    constructor(props: WatchlistProps);
    readonly el: HTMLElement;
    readonly tools: HTMLElement;
    update(next: Partial<Omit<WatchlistProps, 'controller' | 'quotes'>>): void;
    openAdd(): void;
    destroy(): void;
}
MemberTypeDescription
constructor(props: WatchlistProps)
elHTMLElement
toolsHTMLElementThe compact controls (list switcher, add, settings): in the widget's top row until a host lifts them into a header of its own.
update()(next: Partial<Omit<WatchlistProps, 'controller' | 'quotes'>>) => void
openAdd()() => voidOpen the add-symbol search.
destroy()() => void

See also: WatchlistProps.

Interfaces and types

EnableWatchlistOptions

Options for enableWatchlist.

interface EnableWatchlistOptions {
    storage?: WatchlistStorage;
    quotes?: QuoteSource;
    defaultSymbols?: readonly string[];
    rowActions?: readonly WatchlistRowAction[];
    width?: number;
    order?: number;
}
MemberTypeDescription
storage?WatchlistStorageWhere watchlists are kept. Default: the browser's localStorage.
quotes?QuoteSourceWhere quotes come from. Default: the chart's registered providers.
defaultSymbols?readonly string[]The first list's symbols when nothing is kept yet ([] starts empty). Default: a cross-asset starter list (BTC, AAPL, SPY, ES, EURUSD…), kept to what the registered providers list.
rowActions?readonly WatchlistRowAction[]Extra rows in a symbol's right-click menu.
width?number
order?numberPlace among the panel buttons (default 0: first).

See also: QuoteSource, WatchlistRowAction, WatchlistStorage.

SymbolDirectory

Names, logos and the search index: the chart's data, or any source with the same methods.

type SymbolDirectory = Pick<WidgetContext['chart']['data'], 'ready' | 'canonicalSymbol' | 'resolve' | 'symbols' | 'displayPrefix' | 'symbolIcon'>;

From @luxalgo/vela/plugin: WidgetContext.

Watchlist interface

interface Watchlist {
    id: string;
    name: string;
    entries: WatchlistEntry[];
}

See also: WatchlistEntry.

WatchlistAction

An extra row in a symbol's right-click menu (e.g. "Add alert…").

interface WatchlistAction {
    id: string;
    label: string;
    icon?: string;
    run: (symbol: string) => void;
}

WatchlistColumnId

type WatchlistColumnId = 'price' | 'change' | 'changePercent' | 'volume';

WatchlistControllerOptions

interface WatchlistControllerOptions {
    storage: WatchlistStorage;
    seed?: () => WatchlistEntry[];
}
MemberTypeDescription
storageWatchlistStorage
seed?() => WatchlistEntry[]The first list when storage holds none.

See also: WatchlistEntry, WatchlistStorage.

WatchlistEntry

type WatchlistEntry =
    | { kind: 'symbol'; symbol: string }
    | { kind: 'section'; id: string; title: string; collapsed?: boolean };

WatchlistProps

The watchlist's props. controller and quotes are read once; the others can change through update.

interface WatchlistProps {
    controller: WatchlistController;
    quotes: QuoteSource;
    directory?: () => SymbolDirectory | null;
    symbol?: string;
    host?: HTMLElement;
    rowActions?: () => readonly WatchlistAction[];
    picker?: () => SymbolPickerLike | null;
    onSelectSymbol?: (symbol: string) => void;
    onMaximize?: () => void;
    active?: boolean;
}
MemberTypeDescription
controllerWatchlistControllerThe lists and their symbols.
quotesQuoteSourceLive quotes for the rows.
directory?() => SymbolDirectory | nullNames, logos and the search index. Without it, rows show their tickers.
symbol?stringThe symbol in view elsewhere: its row is marked, its details shown underneath.
host?HTMLElementWhere menus and popovers mount (default: the widget's own element).
rowActions?() => readonly WatchlistAction[]Extra rows in a symbol's right-click menu.
picker?() => SymbolPickerLike | nullA symbol picker: "Add symbol" opens it in watchlist mode (else an inline search).
onSelectSymbol?(symbol: string) => voidA row was opened.
onMaximize?() => voidOpen the advanced view (createWatchlistView). Its Maximize button shows only with it.
active?booleanShown or hidden (default shown). Hidden, it keeps no quote feed open (the last quotes stay on the rows); shown again, it resubscribes and measures itself.

See also: QuoteSource, SymbolDirectory, SymbolPickerLike, WatchlistAction, WatchlistController.

WatchlistRowAction

An extra row in a symbol's right-click menu of the sidebar's watchlist (e.g. "Add alert…").

interface WatchlistRowAction {
    id: string;
    label: string;
    icon?: string;
    run: (ctx: WidgetContext, symbol: string) => void;
}

From @luxalgo/vela/plugin: WidgetContext.

WatchlistState

interface WatchlistState {
    lists: Watchlist[];
    activeId: string;
    columns: Record<WatchlistColumnId, boolean>;
    sparklines: boolean;
    details: boolean;
}
MemberTypeDescription
listsWatchlist[]
activeIdstring
columnsRecord<WatchlistColumnId, boolean>The columns the user chose (a narrow panel may hide Volume on top).
sparklinesbooleanEach row's 24h sparkline.
detailsbooleanThe details of the chart's symbol under the list.

See also: Watchlist, WatchlistColumnId.

WatchlistStorage

Where watchlists are kept. load may answer null (nothing kept yet).

interface WatchlistStorage {
    load(): WatchlistState | null | Promise<WatchlistState | null>;
    save(state: WatchlistState): void | Promise<void>;
}

See also: WatchlistState.

WatchlistViewProps

The full view's props. controller and quotes are read once; the others can change through update.

interface WatchlistViewProps {
    controller: WatchlistController;
    quotes: QuoteSource;
    directory?: () => SymbolDirectory | null;
    symbol?: string;
    host?: HTMLElement;
    picker?: () => SymbolPickerLike | null;
    onSelectSymbol?: (symbol: string) => void;
    onMinimize?: () => void;
    onClose?: () => void;
}
MemberTypeDescription
controllerWatchlistControllerThe lists and their symbols.
quotesQuoteSourceLive quotes, and the daily bars the history-based sections read (dailyBars).
directory?() => SymbolDirectory | nullNames, logos, asset types and the search index. Without it, symbols show their tickers.
symbol?stringThe symbol in view on the chart.
host?HTMLElementWhere menus and tooltips mount. Default: the view's own element, which keeps them above it while it covers the page.
picker?() => SymbolPickerLike | nullA symbol picker: Add symbol opens it in watchlist mode. The button shows only with it.
onSelectSymbol?(symbol: string) => voidA symbol was chosen (a row, Enter, Open on chart); the view then returns to the chart.
onMinimize?() => voidBack to the chart, the docked watchlist beside it. The button shows only with it.
onClose?() => voidClose the watchlist altogether. The button shows only with it.

See also: QuoteSource, SymbolDirectory, SymbolPickerLike, WatchlistController.

Constants

WATCHLIST_PANEL_ID

const WATCHLIST_PANEL_ID: 'vela-pro.watchlist';

Namespaces

watchlistModel

namespace watchlistModel {
    function activeList(s: WatchlistState): Watchlist;
    function addList(s: WatchlistState, name: string, entries?: WatchlistEntry[]): WatchlistState;
    function addSection(s: WatchlistState, title: string, afterIndex?: number): WatchlistState;
    function addSymbol(s: WatchlistState, symbol: string, afterIndex?: number): WatchlistState;
    const DEFAULT_COLUMNS: Record<WatchlistColumnId, boolean>;
    function deleteList(s: WatchlistState, id: string): WatchlistState;
    function emptyState(name?: string, entries?: WatchlistEntry[]): WatchlistState;
    function hasSymbol(l: Watchlist, symbol: string): boolean;
    function moveEntry(s: WatchlistState, from: number, to: number): WatchlistState;
    function newId(prefix: string): string;
    function normalizeState(raw: unknown): WatchlistState | null;
    function removeSection(s: WatchlistState, id: string): WatchlistState;
    function removeSymbol(s: WatchlistState, symbol: string): WatchlistState;
    function renameList(s: WatchlistState, id: string, name: string): WatchlistState;
    function selectList(s: WatchlistState, id: string): WatchlistState;
    function symbolsOf(l: Watchlist): string[];
    function updateSection(
        s: WatchlistState,
        id: string,
        patch: { title?: string; collapsed?: boolean },
    ): WatchlistState;
    function visibleEntries(l: Watchlist): Array<{ entry: WatchlistEntry; index: number }>;
    type WatchlistDensity = 'roomy' | 'regular' | 'compact';
    interface WatchlistLayout {
        density: WatchlistDensity;
        columns: Record<WatchlistColumnId, boolean>;
        widths: Record<WatchlistColumnId, number>;
    }
    function watchlistLayout(
        chosen: Record<WatchlistColumnId, boolean>,
        width: number | null,
    ): WatchlistLayout;
    export { LocalWatchlistStorage, MemoryWatchlistStorage };
}
MemberKindDescription
activeList()function
addList()function
addSection()function
addSymbol()functionAdd symbol to the active list (after afterIndex, else at the end). A symbol is listed once.
DEFAULT_COLUMNSconstant
deleteList()functionDelete a list; the last list is never deleted (it is emptied instead).
emptyState()function
hasSymbol()function
LocalWatchlistStorageclass
MemoryWatchlistStorageclass
moveEntry()functionMove the entry at from so it lands at to (indices into the active list).
newId()function
normalizeState()functionA state read back from storage, made whole (a missing field takes its default).
removeSection()functionRemove a section header; its symbols stay, joining the section above.
removeSymbol()function
renameList()function
selectList()function
symbolsOf()functionThe symbols of the active list in order, sections left out: what the arrow keys walk.
updateSection()function
visibleEntries()functionEntries hidden under a collapsed section.
WatchlistDensitytype
WatchlistLayoutinterface
watchlistLayout()functionThe row layout for a panel width px wide: Last, Chg and Chg% stay whatever the width and a narrower panel tightens the row instead; only Volume gives way when even the tightest row has no room for it.

See also: LocalWatchlistStorage, MemoryWatchlistStorage, Watchlist, WatchlistColumnId, WatchlistEntry, WatchlistState.

Re-exports

The following symbols are re-exported from the listed import path and documented on their primary reference page or in their upstream package.

ExportKindExported fromDocumented in
blankQuotefunction@luxalgo/vela-pro-watchlistData feeds
ProviderQuotesclass@luxalgo/vela-pro-watchlistData feeds
Quoteinterface@luxalgo/vela-pro-watchlistData feeds
QuoteSourceinterface@luxalgo/vela-pro-watchlistData feeds
withChangefunction@luxalgo/vela-pro-watchlistData feeds

On this page