Watchlist
API reference for @luxalgo/vela-pro-watchlist, including the watchlist plugin, controller, widgets, and storage port.
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): WatchlistWidgetSee also: WatchlistProps, WatchlistWidget.
createWatchlistView
The full view as a widget: { el, update, destroy }.
function createWatchlistView(props: WatchlistViewProps): WatchlistViewWidgetSee 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): WatchlistControllerSee 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 | nullSee 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;
}| Member | Type | Description |
|---|---|---|
constructor | (opts: WatchlistControllerOptions) | |
ready | Promise<void> | Resolves once storage answered (an async backend). |
state() | () => WatchlistState | |
onChange() | (cb: (s: WatchlistState) => void) => () => void | |
update() | (op: (s: WatchlistState) => WatchlistState) => void | Apply 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;
}| Member | Type | Description |
|---|---|---|
constructor | (props: WatchlistProps) | |
el | HTMLElement | |
tools | HTMLElement | The 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() | () => void | Open 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;
}| Member | Type | Description |
|---|---|---|
storage? | WatchlistStorage | Where watchlists are kept. Default: the browser's localStorage. |
quotes? | QuoteSource | Where 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? | number | Place 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[];
}| Member | Type | Description |
|---|---|---|
storage | WatchlistStorage | |
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;
}| Member | Type | Description |
|---|---|---|
controller | WatchlistController | The lists and their symbols. |
quotes | QuoteSource | Live quotes for the rows. |
directory? | () => SymbolDirectory | null | Names, logos and the search index. Without it, rows show their tickers. |
symbol? | string | The symbol in view elsewhere: its row is marked, its details shown underneath. |
host? | HTMLElement | Where menus and popovers mount (default: the widget's own element). |
rowActions? | () => readonly WatchlistAction[] | Extra rows in a symbol's right-click menu. |
picker? | () => SymbolPickerLike | null | A symbol picker: "Add symbol" opens it in watchlist mode (else an inline search). |
onSelectSymbol? | (symbol: string) => void | A row was opened. |
onMaximize? | () => void | Open the advanced view (createWatchlistView). Its Maximize button shows only with it. |
active? | boolean | Shown 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;
}| Member | Type | Description |
|---|---|---|
lists | Watchlist[] | |
activeId | string | |
columns | Record<WatchlistColumnId, boolean> | The columns the user chose (a narrow panel may hide Volume on top). |
sparklines | boolean | Each row's 24h sparkline. |
details | boolean | The 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;
}| Member | Type | Description |
|---|---|---|
controller | WatchlistController | The lists and their symbols. |
quotes | QuoteSource | Live quotes, and the daily bars the history-based sections read (dailyBars). |
directory? | () => SymbolDirectory | null | Names, logos, asset types and the search index. Without it, symbols show their tickers. |
symbol? | string | The symbol in view on the chart. |
host? | HTMLElement | Where menus and tooltips mount. Default: the view's own element, which keeps them above it while it covers the page. |
picker? | () => SymbolPickerLike | null | A symbol picker: Add symbol opens it in watchlist mode. The button shows only with it. |
onSelectSymbol? | (symbol: string) => void | A symbol was chosen (a row, Enter, Open on chart); the view then returns to the chart. |
onMinimize? | () => void | Back to the chart, the docked watchlist beside it. The button shows only with it. |
onClose? | () => void | Close 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 };
}| Member | Kind | Description |
|---|---|---|
activeList() | function | |
addList() | function | |
addSection() | function | |
addSymbol() | function | Add symbol to the active list (after afterIndex, else at the end). A symbol is listed once. |
DEFAULT_COLUMNS | constant | |
deleteList() | function | Delete a list; the last list is never deleted (it is emptied instead). |
emptyState() | function | |
hasSymbol() | function | |
LocalWatchlistStorage | class | |
MemoryWatchlistStorage | class | |
moveEntry() | function | Move the entry at from so it lands at to (indices into the active list). |
newId() | function | |
normalizeState() | function | A state read back from storage, made whole (a missing field takes its default). |
removeSection() | function | Remove a section header; its symbols stay, joining the section above. |
removeSymbol() | function | |
renameList() | function | |
selectList() | function | |
symbolsOf() | function | The symbols of the active list in order, sections left out: what the arrow keys walk. |
updateSection() | function | |
visibleEntries() | function | Entries hidden under a collapsed section. |
WatchlistDensity | type | |
WatchlistLayout | interface | |
watchlistLayout() | function | 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. |
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.
| Export | Kind | Exported from | Documented in |
|---|---|---|---|
blankQuote | function | @luxalgo/vela-pro-watchlist | Data feeds |
ProviderQuotes | class | @luxalgo/vela-pro-watchlist | Data feeds |
Quote | interface | @luxalgo/vela-pro-watchlist | Data feeds |
QuoteSource | interface | @luxalgo/vela-pro-watchlist | Data feeds |
withChange | function | @luxalgo/vela-pro-watchlist | Data feeds |