@luxalgo/vela 0.6.5 → 0.6.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. package/README.md +16 -16
  2. package/dist/{DataProvider-BmHkcwvJ.d.ts → DataProvider-BSLlBpB9.d.ts} +11 -1
  3. package/dist/{DataProvider-DrN7ZIou.d.cts → DataProvider-BsQM2WNH.d.cts} +11 -1
  4. package/dist/{history-BmyjaVir.d.cts → bottombar-Br4rzx_R.d.ts} +158 -129
  5. package/dist/{history-CvOtsjT5.d.ts → bottombar-Div5zibZ.d.cts} +158 -129
  6. package/dist/{chunk-FQBT4NFM.js → chunk-6WFKTAT4.js} +2797 -2527
  7. package/dist/{chunk-BEJ57HP4.js → chunk-L3I2CCYO.js} +62 -1
  8. package/dist/chunk-W4EJWLEO.js +12 -0
  9. package/dist/{chunk-N6MBJHMV.js → chunk-WVP4XV5A.js} +6050 -3402
  10. package/dist/{contributions-DatoAzMx.d.ts → contributions-Hv4_cOJo.d.cts} +152 -5
  11. package/dist/{contributions-2bEmCF9S.d.cts → contributions-Z12BrWCy.d.ts} +152 -5
  12. package/dist/index.cjs +2798 -2484
  13. package/dist/index.d.cts +44 -16
  14. package/dist/index.d.ts +44 -16
  15. package/dist/index.js +2 -2
  16. package/dist/{options-YdiaaVjt.d.cts → options-BaVTMXaO.d.cts} +48 -2
  17. package/dist/{options-YdiaaVjt.d.ts → options-BaVTMXaO.d.ts} +48 -2
  18. package/dist/{plugin-Bcone6Vh.d.ts → plugin-9koBjc5H.d.ts} +6 -4
  19. package/dist/{plugin-DO_DX0gp.d.cts → plugin-BXhDHTYn.d.cts} +6 -4
  20. package/dist/plugin.cjs +44 -0
  21. package/dist/plugin.d.cts +4 -4
  22. package/dist/plugin.d.ts +4 -4
  23. package/dist/plugin.js +1 -1
  24. package/dist/providers/binance.cjs +16 -0
  25. package/dist/providers/binance.d.cts +5 -2
  26. package/dist/providers/binance.d.ts +5 -2
  27. package/dist/providers/binance.js +7 -0
  28. package/dist/providers/coinbase.cjs +16 -0
  29. package/dist/providers/coinbase.d.cts +5 -2
  30. package/dist/providers/coinbase.d.ts +5 -2
  31. package/dist/providers/coinbase.js +7 -0
  32. package/dist/providers/hyperliquid.cjs +16 -0
  33. package/dist/providers/hyperliquid.d.cts +5 -2
  34. package/dist/providers/hyperliquid.d.ts +5 -2
  35. package/dist/providers/hyperliquid.js +7 -0
  36. package/dist/ui.d.cts +1 -1
  37. package/dist/ui.d.ts +1 -1
  38. package/dist/vela.global.js +2824 -2484
  39. package/dist/vela.global.min.js +48 -48
  40. package/dist/widget.cjs +35791 -34070
  41. package/dist/widget.d.cts +80 -275
  42. package/dist/widget.d.ts +80 -275
  43. package/dist/widget.js +61 -1313
  44. package/dist/workspace.cjs +1700 -995
  45. package/dist/workspace.d.cts +120 -15
  46. package/dist/workspace.d.ts +120 -15
  47. package/dist/workspace.js +7 -2281
  48. package/package.json +1 -1
package/README.md CHANGED
@@ -1,35 +1,35 @@
1
1
  # Vela
2
2
 
3
3
  A fast, extensible financial charting library with its own native canvas renderer, a
4
- headless core, a batteries-included widget, and a plugin SDK for custom chart types and
4
+ headless core, a batteries-included shell, and a plugin SDK for custom chart types and
5
5
  renderer layers.
6
6
 
7
7
  - **`vela`** — the headless chart: data model, engines, drawings, providers, native renderer.
8
- - **`vela/widget`** — the full chart app: topbar (symbol / timeframe / style / indicators),
9
- status line, watermark, bottom bar (ranges, clock, timezone), object tree, keyboard-first UX.
10
- - **`vela/ui`** the component kit the widget is built on: design tokens, overlay chrome
8
+ - **`vela/workspace`** — the full chart app: one chart (`layout: false`) or a grid of
9
+ them under one shared topbar (symbol / timeframe / style / indicators), status line,
10
+ watermark, bottom bar (ranges, clock, timezone), object tree, keyboard-first UX,
11
+ named cells, sync groups and one persisted state document.
12
+ - **`vela/ui`** — the component kit the shell is built on: design tokens, overlay chrome
11
13
  ([Zag.js](https://zagjs.com) menu/dialog/drawer/tooltip), form primitives (switch, select,
12
14
  number, text, color, popover), and the `KeymapManager`.
13
15
  - **`vela/plugin`** — the extension SDK: chart types, renderer layers, native indicators.
14
- - **`vela/workspace`** — the multi-chart shell: a grid of full charts under one shared
15
- topbar, with named cells, sync groups and one persisted state document.
16
16
  - **`vela/providers/*`** — data providers (Binance, Coinbase, Hyperliquid).
17
17
 
18
18
  ## Quick start
19
19
 
20
20
  ```ts
21
- import { VelaWidget } from 'vela/widget';
21
+ import { VelaWorkspace } from 'vela/workspace';
22
22
  import { BinanceProvider } from 'vela/providers/binance';
23
23
 
24
- const widget = new VelaWidget('#chart', {
24
+ const chart = new VelaWorkspace('#chart', {
25
+ layout: false, // one chart; '2h' | '4' | '8' | … for a multi-chart grid
25
26
  symbol: 'BTCUSDT', // bare = first declared provider listing it; 'binance:BTCUSDT' pins the venue
26
27
  timeframe: '60',
27
28
  live: true,
28
29
  theme: 'dark',
29
30
  providers: { binance: () => new BinanceProvider() },
30
- persist: true, // restore the full state document — market, style, timezone, renderer
31
- // config, drawings and indicators — from localStorage
32
- urlState: true, // ?symbol=…&interval=… shareable links
31
+ persist: true, // restore the full state document — market, style, timezone, renderer
32
+ // config, drawings and indicators — from localStorage
33
33
  });
34
34
  ```
35
35
 
@@ -67,11 +67,11 @@ value** — via `handle.context()` (read-only snapshots, worker-safe). See the
67
67
  [API reference](docs/user/api-reference.md#reading-a-scripts-execution-context), and
68
68
  [Scripting engines](docs/user/scripting-engines.md) for the addon and for writing your own.
69
69
 
70
- The widget takes an **indicator manifest** — inline JSON, a URL returning it, or an async
70
+ The shell takes an **indicator manifest** — inline JSON, a URL returning it, or an async
71
71
  loader (`() => Promise<manifest>`):
72
72
 
73
73
  ```ts
74
- new VelaWidget('#chart', {
74
+ new VelaWorkspace('#chart', {
75
75
  // …
76
76
  engines: { pine: () => new PineEngine() },
77
77
  indicators: '/indicators.json', // or an inline [{ name, script | url, language?, enabled? }]
@@ -82,7 +82,7 @@ new VelaWidget('#chart', {
82
82
 
83
83
  Type a **letter** → symbol search. Type a **digit** → timeframe entry (`15`, `4h`, `D`, `3M`…).
84
84
  `mod+alt+S` (Ctrl+Alt+S, ⌥⌘S on macOS) → screenshot. `?` → the shortcuts panel. Bindings are declarative
85
- (`widget.keymap.register({...})`) — plugins register theirs the same way.
85
+ (`chart.keymap.register({...})`) — plugins register theirs the same way.
86
86
 
87
87
  ## Extending (plugin SDK)
88
88
 
@@ -104,14 +104,14 @@ registerRendererLayer({
104
104
  });
105
105
  ```
106
106
 
107
- A registered chart type automatically appears in the widget's style dropdown; a chart
107
+ A registered chart type automatically appears in the shell's style dropdown; a chart
108
108
  type's `dataEngine` pushes to its layer's channel with zero extra wiring. See
109
109
  [docs/contributing/plugin-sdk.md](docs/contributing/plugin-sdk.md).
110
110
 
111
111
  ## Documentation
112
112
 
113
113
  Full documentation lives in [docs/](docs/index.md) — user guides ([quickstart](docs/user/quickstart.md),
114
- [the widget](docs/user/widget.md), [options](docs/user/options.md), [API reference](docs/user/api-reference.md)),
114
+ [the workspace](docs/user/workspace.md), [options](docs/user/options.md), [API reference](docs/user/api-reference.md)),
115
115
  [architecture](docs/architecture/overview.md), and [contributing](docs/contributing/setup.md) guides
116
116
  including the [plugin SDK](docs/contributing/plugin-sdk.md).
117
117
 
@@ -1,4 +1,4 @@
1
- import { M as MarketConfig, O as OHLCV, U as Unsubscribe } from './options-YdiaaVjt.js';
1
+ import { M as MarketConfig, O as OHLCV, U as Unsubscribe } from './options-BaVTMXaO.js';
2
2
 
3
3
  /**
4
4
  * Symbol metadata an engine may need (e.g. Pine `syminfo.*`). Free-form beyond
@@ -131,6 +131,16 @@ interface DataProvider {
131
131
  listSymbols?(): Promise<SymbolDescriptor[]>;
132
132
  /** Per-symbol metadata for engine `syminfo.*`. Absent ⇒ the engine synthesizes a fallback. */
133
133
  getSymbolInfo?(ticker: string): Promise<SymbolInfo | undefined>;
134
+ /**
135
+ * The icon URL for one of THIS provider's symbols — the provider owns the knowledge
136
+ * of where its asset class's icons live (a crypto CDN, a self-hosted store), the
137
+ * shells own the rendering (round badge, colored-initials fallback). Called lazily,
138
+ * per RENDERED row — never per index build — so it must be cheap and synchronous.
139
+ * `undefined` ⇒ no icon (the initials badge shows). Absent ⇒ same. The URL must be
140
+ * CORS-clean (`Access-Control-Allow-Origin`) or drawing it taints the canvas and
141
+ * breaks the PNG export — a load error falls back to initials either way.
142
+ */
143
+ resolveSymbolIcon?(symbol: SymbolDescriptor): string | undefined;
134
144
  /**
135
145
  * Open a true live stream for `ticker`/`timeframe`. Each call to `onBar` delivers
136
146
  * the forming candle (or a freshly-closed one). Returns an unsubscribe fn. Absent
@@ -1,4 +1,4 @@
1
- import { M as MarketConfig, O as OHLCV, U as Unsubscribe } from './options-YdiaaVjt.cjs';
1
+ import { M as MarketConfig, O as OHLCV, U as Unsubscribe } from './options-BaVTMXaO.cjs';
2
2
 
3
3
  /**
4
4
  * Symbol metadata an engine may need (e.g. Pine `syminfo.*`). Free-form beyond
@@ -131,6 +131,16 @@ interface DataProvider {
131
131
  listSymbols?(): Promise<SymbolDescriptor[]>;
132
132
  /** Per-symbol metadata for engine `syminfo.*`. Absent ⇒ the engine synthesizes a fallback. */
133
133
  getSymbolInfo?(ticker: string): Promise<SymbolInfo | undefined>;
134
+ /**
135
+ * The icon URL for one of THIS provider's symbols — the provider owns the knowledge
136
+ * of where its asset class's icons live (a crypto CDN, a self-hosted store), the
137
+ * shells own the rendering (round badge, colored-initials fallback). Called lazily,
138
+ * per RENDERED row — never per index build — so it must be cheap and synchronous.
139
+ * `undefined` ⇒ no icon (the initials badge shows). Absent ⇒ same. The URL must be
140
+ * CORS-clean (`Access-Control-Allow-Origin`) or drawing it taints the canvas and
141
+ * breaks the PNG export — a load error falls back to initials either way.
142
+ */
143
+ resolveSymbolIcon?(symbol: SymbolDescriptor): string | undefined;
134
144
  /**
135
145
  * Open a true live stream for `ticker`/`timeframe`. Each call to `onBar` delivers
136
146
  * the forming candle (or a freshly-closed one). Returns an unsubscribe fn. Absent
@@ -1,101 +1,6 @@
1
- import { V as VisibleRangePreset } from './options-YdiaaVjt.cjs';
2
- import { D as DataProvider } from './DataProvider-DrN7ZIou.cjs';
3
- import { S as ScriptingEngine, V as Vela } from './contributions-2bEmCF9S.cjs';
4
-
5
- interface RangePreset {
6
- /** Button label. */
7
- id: string;
8
- /** Timeframe to switch to for this range. */
9
- tf: string;
10
- /** The core visible-range preset framed once the chart is ready. */
11
- preset: VisibleRangePreset;
12
- /**
13
- * Bars the window needs AT `tf` — the fetch budget for the rebuild. Without it the
14
- * chart loads its default depth and the framed window is clipped to whatever
15
- * history happens to be loaded (a "1D" that only shows 16 hours). Includes a small
16
- * margin; `ALL` asks for as much history as the provider will serve.
17
- */
18
- bars: number;
19
- }
20
- /**
21
- * Range chips — each pairs a timeframe, a visible window, and the fetch depth that
22
- * window needs. Resolutions follow the reference: the shorter the range, the finer the
23
- * bars (1 day of 1-minute bars … 5 years of weekly bars).
24
- */
25
- declare const RANGE_PRESETS: readonly RangePreset[];
26
- interface BottombarOptions {
27
- timezone: string;
28
- onRange: (preset: RangePreset) => void;
29
- onTimezone: (zone: string) => void;
30
- /** RTH/ETH toggled by the user. Fires only while the toggle is ENABLED (see {@link Bottombar.setSession}). */
31
- onSession?: (session: 'regular' | 'extended') => void;
32
- onSettingsClick?: () => void;
33
- }
34
- declare class Bottombar {
35
- readonly el: HTMLElement;
36
- private readonly clockEl;
37
- private readonly tzLabelEl;
38
- private readonly tzButton;
39
- private readonly tzMenu;
40
- private readonly settingsTip;
41
- private readonly rangeButtons;
42
- private readonly sessionButtons;
43
- private sessionEl;
44
- private timezone;
45
- private timer;
46
- constructor(host: HTMLElement, opts: BottombarOptions);
47
- setTimezone(zone: string): void;
48
- /** Highlight (or clear with null) the active range chip — cleared on manual tf changes. */
49
- setActiveRange(id: string | null): void;
50
- /**
51
- * Reflect the ACTIVE chart's session posture. `enabled: false` (a continuous
52
- * market, or metadata not landed yet) HIDES the toggle entirely — RTH/ETH is
53
- * meaningless there. Enabled, the chips appear and the active one tracks the
54
- * chart's current session.
55
- */
56
- setSession(state: {
57
- session: 'regular' | 'extended';
58
- enabled: boolean;
59
- }): void;
60
- destroy(): void;
61
- private tzItems;
62
- private tick;
63
- }
64
-
65
- interface IndicatorManifestEntry {
66
- name: string;
67
- /** Inline script source (one of script/url required). */
68
- script?: string;
69
- /** Fetch the source from here instead (resolved relative to the manifest URL). */
70
- url?: string;
71
- /** Engine language (default: the chart's default engine). */
72
- language?: string;
73
- /** Add to the chart at startup (default true). Disabled entries only appear in pickers. */
74
- enabled?: boolean;
75
- /** Picker grouping (default 'Indicators'). */
76
- category?: string;
77
- }
78
- type IndicatorManifest = IndicatorManifestEntry[] | {
79
- indicators: IndicatorManifestEntry[];
80
- };
81
- /** A manifest entry with its source resolved and ready for `chart.addIndicator`. */
82
- interface ResolvedIndicator {
83
- name: string;
84
- script: string;
85
- language?: string;
86
- enabled: boolean;
87
- category?: string;
88
- }
89
- /** An async manifest source — called once at resolution time. The escape hatch for
90
- * manifests that a URL can't express: a filesystem read, an authenticated API, a
91
- * bundler dynamic import. A rejection behaves like a failing manifest URL. */
92
- type IndicatorLoader = () => Promise<IndicatorManifest>;
93
- /** Load the indicator list: a manifest object, a URL string returning the manifest JSON,
94
- * or an async loader function returning the manifest. Entries with `url` sources are
95
- * fetched here too (relative to the manifest URL when there is one). Entries that fail
96
- * to resolve are dropped with a console warning — one broken script must not take the
97
- * chart down. */
98
- declare function resolveIndicators(config: string | IndicatorManifest | IndicatorLoader, fetchImpl?: typeof fetch): Promise<ResolvedIndicator[]>;
1
+ import { D as DataProvider } from './DataProvider-BSLlBpB9.js';
2
+ import { S as ScriptingEngine, V as Vela } from './contributions-Z12BrWCy.js';
3
+ import { V as VisibleRangePreset } from './options-BaVTMXaO.js';
99
4
 
100
5
  /** The linkable dimensions. `crosshair` mirrors the pointer time onto same-group
101
6
  * cells as GHOST crosshairs (renderers without the optional `setExternalCrosshair`
@@ -161,6 +66,12 @@ interface CellState {
161
66
  manifest: string[];
162
67
  natives: string[];
163
68
  };
69
+ /** Third-party per-chart state, by namespaced key (`'vendor.feature'`) — written and
70
+ * read by registered state-persistence handlers (`registerStatePersistence`, scope
71
+ * `'cell'`). Values are OPAQUE here: the codec preserves entries verbatim — a key
72
+ * whose handler is absent this session still round-trips — and each handler
73
+ * validates its own payload at restore. JSON-serializable values only. */
74
+ ext?: Record<string, unknown>;
164
75
  }
165
76
  /** One entry of the document's `charts` array: a chart's state plus its cell IDENTITY. */
166
77
  interface ChartState extends CellState {
@@ -191,6 +102,9 @@ interface WorkspaceState {
191
102
  /** Per-chart state, one entry per SLOT (a single `c1` entry for the widget).
192
103
  * Ids are unique — the codec drops id-less entries and keeps the LAST duplicate. */
193
104
  charts: ChartState[];
105
+ /** Third-party document-level state, by namespaced key (`'vendor.feature'`) — the
106
+ * `scope: 'global'` counterpart of {@link CellState.ext}, same opacity contract. */
107
+ ext?: Record<string, unknown>;
194
108
  }
195
109
  declare function encodeState(state: WorkspaceState): string;
196
110
  /** Parse + sanitize a persisted payload. Null on anything unusable (wrong version,
@@ -203,8 +117,43 @@ declare function decodeState(raw: string): WorkspaceState | null;
203
117
  */
204
118
  declare function sanitizeState(doc: unknown): WorkspaceState | null;
205
119
 
206
- /** The storage contract BOTH shells persist through (the widget and the workspace —
207
- * one name, one shape). Methods may be synchronous or return promises. */
120
+ interface IndicatorManifestEntry {
121
+ name: string;
122
+ /** Inline script source (one of script/url required). */
123
+ script?: string;
124
+ /** Fetch the source from here instead (resolved relative to the manifest URL). */
125
+ url?: string;
126
+ /** Engine language (default: the chart's default engine). */
127
+ language?: string;
128
+ /** Add to the chart at startup (default true). Disabled entries only appear in pickers. */
129
+ enabled?: boolean;
130
+ /** Picker grouping (default 'Indicators'). */
131
+ category?: string;
132
+ }
133
+ type IndicatorManifest = IndicatorManifestEntry[] | {
134
+ indicators: IndicatorManifestEntry[];
135
+ };
136
+ /** A manifest entry with its source resolved and ready for `chart.addIndicator`. */
137
+ interface ResolvedIndicator {
138
+ name: string;
139
+ script: string;
140
+ language?: string;
141
+ enabled: boolean;
142
+ category?: string;
143
+ }
144
+ /** An async manifest source — called once at resolution time. The escape hatch for
145
+ * manifests that a URL can't express: a filesystem read, an authenticated API, a
146
+ * bundler dynamic import. A rejection behaves like a failing manifest URL. */
147
+ type IndicatorLoader = () => Promise<IndicatorManifest>;
148
+ /** Load the indicator list: a manifest object, a URL string returning the manifest JSON,
149
+ * or an async loader function returning the manifest. Entries with `url` sources are
150
+ * fetched here too (relative to the manifest URL when there is one). Entries that fail
151
+ * to resolve are dropped with a console warning — one broken script must not take the
152
+ * chart down. */
153
+ declare function resolveIndicators(config: string | IndicatorManifest | IndicatorLoader, fetchImpl?: typeof fetch): Promise<ResolvedIndicator[]>;
154
+
155
+ /** The storage contract BOTH shells persist through (the widget wrapper and the
156
+ * workspace — one name, one shape). Methods may be synchronous or return promises. */
208
157
  interface VelaStorage {
209
158
  get(key: string): string | null | Promise<string | null>;
210
159
  set(key: string, value: string): void | Promise<void>;
@@ -222,32 +171,37 @@ type WidgetStorage = VelaStorage;
222
171
  * shell's own key is used as-is (the historical behavior).
223
172
  */
224
173
  declare function localStorageAdapter(storageKey?: string): WidgetStorage;
225
- interface PersistedState {
226
- symbol?: string;
227
- timeframe?: string;
228
- priceStyle?: string;
229
- timezone?: string;
230
- bars?: string;
231
- /** Trading session (`regular` | `extended`) — URL param `session`. */
232
- session?: string;
233
- watermark?: string;
234
- /** Comma-joined favorite drawing-tool types. */
235
- favorites?: string;
174
+
175
+ /** The host-facing option: visible entries per side, in render order. An undeclared
176
+ * side falls back to its default list. */
177
+ interface TopbarComposition {
178
+ left?: readonly string[];
179
+ right?: readonly string[];
236
180
  }
237
- /** Parse a LEGACY prefs payload (never throws junk yields `{}`). */
238
- declare function parsePersisted(raw: string | null): PersistedState;
239
- /** Load the persisted state synchronous result for sync storages, else a promise. */
240
- declare function loadPersisted(storage: WidgetStorage, storageKey: string): PersistedState | Promise<PersistedState>;
241
- /** Save (fire-and-forget async adapter failures are the adapter's concern). */
242
- declare function savePersisted(storage: WidgetStorage, storageKey: string, state: PersistedState): void;
243
- /**
244
- * LEGACY migration — convert the widget's pre-unified three-key layout (prefs under
245
- * the main key, renderer config under `<key>:config`, drawings under `<key>:drawings`)
246
- * into ONE unified state document (the same format the workspace persists, with a
247
- * single `c1` cell). Null when the payload holds no usable state. Pure — the caller
248
- * reads the keys, then rewrites the main key and drops the legacy sub-keys.
249
- */
250
- declare function legacyWidgetState(prefs: PersistedState, rawConfig: string | null, rawDrawings: string | null): WorkspaceState | null;
181
+ /** The built-in entry vocabulary (everything else in a list is a contributed-action id).
182
+ * `'layout'` renders only on multi-chart shells and `'indicators'` only while an
183
+ * indicator surface existsthe built-in picker (the deprecated `indicatorPicker:
184
+ * false` still removes it) or a slot OVERRIDE replacing it — so listing them is
185
+ * necessary but not sufficient. */
186
+ declare const TOPBAR_BUILTIN_IDS: readonly ["symbol", "timeframes", "style", "layout", "indicators", "actions", "undo-redo", "alerts", "panels", "screenshot"];
187
+ /** The default left side — the current shell composition, verbatim. */
188
+ declare const TOPBAR_DEFAULT_LEFT: readonly string[];
189
+ /** The default right side (the `margin-left: auto` cluster). */
190
+ declare const TOPBAR_DEFAULT_RIGHT: readonly string[];
191
+ /** A composition with both sides resolved (defaults applied, duplicates dropped). */
192
+ interface ResolvedTopbarComposition {
193
+ left: string[];
194
+ right: string[];
195
+ }
196
+ /** Resolve the host option: absent side ⇒ its default list; a duplicated id keeps its
197
+ * FIRST occurrence (left before right) so an entry never renders twice. `'actions'`
198
+ * is the exception — it is a flow SLOT each side legitimately owns (the defaults
199
+ * carry one on both), so it dedupes per side only. */
200
+ declare function resolveTopbarComposition(opt?: TopbarComposition): ResolvedTopbarComposition;
201
+ /** Whether an entry id is visible anywhere in the resolved composition. */
202
+ declare function topbarHas(comp: ResolvedTopbarComposition, id: string): boolean;
203
+ /** The non-built-in entries — contributed-action ids PINNED to a list position. */
204
+ declare function pinnedTopbarActionIds(comp: ResolvedTopbarComposition): string[];
251
205
 
252
206
  /** What a shell (widget or workspace) accepts BEYOND the chart options themselves. */
253
207
  interface VelaShellOptions {
@@ -274,10 +228,25 @@ interface VelaShellOptions {
274
228
  statusline?: boolean;
275
229
  watermark?: boolean;
276
230
  bottombar?: boolean;
231
+ /** Declarative topbar composition: `{ left, right }` lists of the VISIBLE entries,
232
+ * in render order — built-in ids (`'symbol'`, `'timeframes'`, `'style'`,
233
+ * `'layout'`, `'indicators'`, `'actions'`, `'undo-redo'`, `'alerts'`, `'panels'`,
234
+ * `'screenshot'`) and/or contributed-action ids (naming one PINS it there,
235
+ * overriding its `align`/`order`; `'actions'` is where the unlisted ones flow).
236
+ * An undeclared side keeps its default. An explicit list is that side's complete
237
+ * contract — it also FREEZES it: chrome a future release adds will not appear.
238
+ * Hiding a built-in removes its mobile entry and keyboard chord too (`mod+alt+S`
239
+ * for `'screenshot'`); Ctrl+Z / Ctrl+Y stay — they belong to editing, not to the
240
+ * `'undo-redo'` buttons. */
241
+ topbar?: TopbarComposition;
277
242
  /** The built-in indicator picker's entry points — the topbar button, the mobile-bar
278
- * item, and the `/` shortcut. `false` removes them, for hosts that replace the
279
- * picker with their own indicator UI (e.g. a contributed topbar action opening a
280
- * custom dialog). The `indicators` manifest still resolves and auto-adds. */
243
+ * item, and the `/` shortcut. `false` removes them. The `indicators` manifest
244
+ * still resolves and auto-adds.
245
+ * @deprecated Removed in 0.7.0. To HIDE the built-in surface, omit `'indicators'`
246
+ * from `topbar.left` (same effect: no button, no mobile stop, no `/`, no dialog).
247
+ * To REPLACE it, a plugin registers its action under the id `'indicators'`
248
+ * (`registerWidgetAction`) — the override takes the slot's whole surface and
249
+ * needs no shell option at all. */
281
250
  indicatorPicker?: boolean;
282
251
  /** Chrome size class. `'auto'` (default) follows the CONTAINER width plus a
283
252
  * coarse-pointer heuristic; `'mobile'` / `'desktop'` pin it. Mobile swaps the
@@ -332,4 +301,64 @@ declare class WidgetHistory {
332
301
  private notify;
333
302
  }
334
303
 
335
- export { Bottombar as B, type CellState as C, type IndicatorLoader as I, type PanelsState as P, type ResolvedIndicator as R, type SyncSetting as S, type TrackSizes as T, type VelaStorage as V, WidgetHistory as W, type RangePreset as a, type VelaShellOptions as b, type SyncOptions as c, type SyncKind as d, type WorkspaceState as e, type ChartState as f, decodeState as g, encodeState as h, type PersistedState as i, type BottombarOptions as j, type IndicatorManifest as k, type IndicatorManifestEntry as l, RANGE_PRESETS as m, type WidgetStorage as n, legacyWidgetState as o, loadPersisted as p, localStorageAdapter as q, parsePersisted as r, sanitizeState as s, resolveIndicators as t, savePersisted as u };
304
+ interface RangePreset {
305
+ /** Button label. */
306
+ id: string;
307
+ /** Timeframe to switch to for this range. */
308
+ tf: string;
309
+ /** The core visible-range preset framed once the chart is ready. */
310
+ preset: VisibleRangePreset;
311
+ /**
312
+ * Bars the window needs AT `tf` — the fetch budget for the rebuild. Without it the
313
+ * chart loads its default depth and the framed window is clipped to whatever
314
+ * history happens to be loaded (a "1D" that only shows 16 hours). Includes a small
315
+ * margin; `ALL` asks for as much history as the provider will serve.
316
+ */
317
+ bars: number;
318
+ }
319
+ /**
320
+ * Range chips — each pairs a timeframe, a visible window, and the fetch depth that
321
+ * window needs. Resolutions follow the reference: the shorter the range, the finer the
322
+ * bars (1 day of 1-minute bars … 5 years of weekly bars).
323
+ */
324
+ declare const RANGE_PRESETS: readonly RangePreset[];
325
+ interface BottombarOptions {
326
+ timezone: string;
327
+ onRange: (preset: RangePreset) => void;
328
+ onTimezone: (zone: string) => void;
329
+ /** RTH/ETH toggled by the user. Fires only while the toggle is ENABLED (see {@link Bottombar.setSession}). */
330
+ onSession?: (session: 'regular' | 'extended') => void;
331
+ onSettingsClick?: () => void;
332
+ }
333
+ declare class Bottombar {
334
+ readonly el: HTMLElement;
335
+ private readonly clockEl;
336
+ private readonly tzLabelEl;
337
+ private readonly tzButton;
338
+ private readonly tzMenu;
339
+ private readonly settingsTip;
340
+ private readonly rangeButtons;
341
+ private readonly sessionButtons;
342
+ private sessionEl;
343
+ private timezone;
344
+ private timer;
345
+ constructor(host: HTMLElement, opts: BottombarOptions);
346
+ setTimezone(zone: string): void;
347
+ /** Highlight (or clear with null) the active range chip — cleared on manual tf changes. */
348
+ setActiveRange(id: string | null): void;
349
+ /**
350
+ * Reflect the ACTIVE chart's session posture. `enabled: false` (a continuous
351
+ * market, or metadata not landed yet) HIDES the toggle entirely — RTH/ETH is
352
+ * meaningless there. Enabled, the chips appear and the active one tracks the
353
+ * chart's current session.
354
+ */
355
+ setSession(state: {
356
+ session: 'regular' | 'extended';
357
+ enabled: boolean;
358
+ }): void;
359
+ destroy(): void;
360
+ private tzItems;
361
+ private tick;
362
+ }
363
+
364
+ export { Bottombar as B, type CellState as C, type IndicatorLoader as I, type PanelsState as P, type ResolvedIndicator as R, type SyncSetting as S, type TrackSizes as T, type VelaStorage as V, WidgetHistory as W, type RangePreset as a, type VelaShellOptions as b, type SyncOptions as c, type SyncKind as d, type WorkspaceState as e, type ChartState as f, decodeState as g, encodeState as h, type TopbarComposition as i, type BottombarOptions as j, type IndicatorManifest as k, type IndicatorManifestEntry as l, RANGE_PRESETS as m, type ResolvedTopbarComposition as n, TOPBAR_BUILTIN_IDS as o, TOPBAR_DEFAULT_LEFT as p, TOPBAR_DEFAULT_RIGHT as q, type WidgetStorage as r, sanitizeState as s, localStorageAdapter as t, pinnedTopbarActionIds as u, resolveIndicators as v, resolveTopbarComposition as w, topbarHas as x };