# Layout and panels (/vela-pro/api/layout)



This page documents the layout primitives and UI utilities exported by `@luxalgo/vela-pro`, including the side rail, bottom dock, panel registration helpers, DOM utilities, icons, and value formatters.

Import symbols on this page from `@luxalgo/vela-pro`. Related guides: [Workspace layout](/vela-pro/charts/interface), [Custom panels and widgets](/vela-pro/modules/extending/custom-widgets), [Interface layout](/vela-pro/customization/interface).

Feature enablers for this area ([`enableBottomDock`](/vela-pro/api/enablers#enablebottomdock), [`enableSchemeTracking`](/vela-pro/api/enablers#enableschemetracking), [`enableSideRail`](/vela-pro/api/enablers#enablesiderail)) are documented on [Enablers and options](/vela-pro/api/enablers).

## Functions [#functions]

### `append` [#append]

```typescript
function append(el: Element, children: readonly Child[]): void
```

See also: [`Child`](/vela-pro/api/layout#child).

### `bottomDock` [#bottomdock]

The bottom dock of a shell (by its root or a context), or null when it is off.

```typescript
function bottomDock(host: HTMLElement | WidgetContext): BottomDockHandle | null
```

See also: [`BottomDockHandle`](/vela-pro/api/layout#bottomdockhandle). From `@luxalgo/vela/plugin`: `WidgetContext`.

### `bottomPanels` [#bottompanels]

```typescript
function bottomPanels(): BottomPanelDescriptor[]
```

See also: [`BottomPanelDescriptor`](/vela-pro/api/layout#bottompaneldescriptor).

### `clampDockHeight` [#clampdockheight]

Clamp a requested dock height: never under `min`, never squeezing the charts under `chartFloor`.

```typescript
function clampDockHeight(px: number, l: DockHeightLimits): number
```

See also: [`DockHeightLimits`](/vela-pro/api/layout#dockheightlimits).

### `decimalsOf` [#decimalsof]

Decimals that print `tick` exactly (0.01 → 2, 0.5 → 1, 1 → 0).

Also exported from `@luxalgo/vela-pro/plugin`.

```typescript
function decimalsOf(tick: number): number
```

### `describeRailEntry` [#describerailentry]

Give a rail entry (a side panel or an item) its hover-card copy.

Also exported from `@luxalgo/vela-pro/plugin`.

```typescript
function describeRailEntry(id: string, hint: RailHint): void
```

See also: [`RailHint`](/vela-pro/api/layout#railhint).

### `ensureProUi` [#ensureproui]

Inject Pro's base stylesheet into `doc` (idempotent).

Also exported from `@luxalgo/vela-pro/plugin`.

```typescript
function ensureProUi(doc?: Document): void
```

Default: `doc = document`.

### `formatAgo` [#formatago]

`3m ago`, `just now`.

```typescript
function formatAgo(ms: number, now?: number): string
```

Default: `now = Date.now()`.

### `formatClock` [#formatclock]

`14:05:09`: a clock time.

Also exported from `@luxalgo/vela-pro/plugin`.

```typescript
function formatClock(ms: number): string
```

### `formatCompact` [#formatcompact]

A large count compactly (1.2K, 3.4M).

Also exported from `@luxalgo/vela-pro/plugin`.

```typescript
function formatCompact(value: number | null | undefined): string
```

### `formatDate` [#formatdate]

```typescript
function formatDate(ms: number | null | undefined, timeZone?: string): string
```

### `formatDateTime` [#formatdatetime]

`28 Oct 2026, 14:05` in the given IANA zone (default: the browser's).

Also exported from `@luxalgo/vela-pro/plugin`.

```typescript
function formatDateTime(ms: number | null | undefined, timeZone?: string): string
```

### `formatDuration` [#formatduration]

A duration in ms as `2d 4h`, `3h 12m`, `45m`, `12s`.

Also exported from `@luxalgo/vela-pro/plugin`.

```typescript
function formatDuration(ms: number | null | undefined): string
```

### `formatMoney` [#formatmoney]

A money amount (2 decimals), signed when `signed`.

Also exported from `@luxalgo/vela-pro/plugin`.

```typescript
function formatMoney(
    value: number | null | undefined,
    opts?: { signed?: boolean; currency?: string; decimals?: number },
): string
```

### `formatPercent` [#formatpercent]

Also exported from `@luxalgo/vela-pro/plugin`.

```typescript
function formatPercent(
    value: number | null | undefined,
    opts?: { signed?: boolean; decimals?: number },
): string
```

### `formatPrice` [#formatprice]

A price at the market's tick precision.

Also exported from `@luxalgo/vela-pro/plugin`.

```typescript
function formatPrice(value: number | null | undefined, tick?: number): string
```

Default: `tick = 0.01`.

### `formatQty` [#formatqty]

A quantity: as many decimals as it carries, up to 8.

Also exported from `@luxalgo/vela-pro/plugin`.

```typescript
function formatQty(value: number | null | undefined): string
```

### `h` [#h]

Also exported from `@luxalgo/vela-pro/plugin`.

```typescript
function h<K extends keyof HTMLElementTagNameMap>(
    tag: K,
    props?: ElementProps,
    ...children: Child[],
): HTMLElementTagNameMap[K]
```

See also: [`Child`](/vela-pro/api/layout#child), [`ElementProps`](/vela-pro/api/layout#elementprops).

### `icon` [#icon]

A Vela icon (registry id) as an element: `size` in px.

Also exported from `@luxalgo/vela-pro/plugin`.

```typescript
function icon(id: string, size?: number): HTMLElement
```

Default: `size = 16`.

### `pressDockPanel` [#pressdockpanel]

A press on a panel's toggle (its tab, its rail button): opens the dock on that panel; on the panel already showing, closes the dock (the rail's own idiom for side panels).

```typescript
function pressDockPanel(state: DockState, id: string): DockState
```

See also: [`DockState`](/vela-pro/api/layout#dockstate).

### `railItems` [#railitems]

```typescript
function railItems(): RailItemDescriptor[]
```

See also: [`RailItemDescriptor`](/vela-pro/api/layout#railitemdescriptor).

### `registerBottomPanel` [#registerbottompanel]

Register (or replace) a bottom panel. Shells built afterwards dock it.

Also exported from `@luxalgo/vela-pro/plugin`.

```typescript
function registerBottomPanel(desc: BottomPanelDescriptor): () => void
```

See also: [`BottomPanelDescriptor`](/vela-pro/api/layout#bottompaneldescriptor).

### `registerProIcons` [#registerproicons]

Register Pro's icons (idempotent). Every enabler calls it before projecting chrome.

Also exported from `@luxalgo/vela-pro/plugin`.

```typescript
function registerProIcons(): void
```

### `registerRailItem` [#registerrailitem]

Register (or replace) a rail item. Shells already built show it on their next refresh.

```typescript
function registerRailItem(desc: RailItemDescriptor): () => void
```

See also: [`RailItemDescriptor`](/vela-pro/api/layout#railitemdescriptor).

### `setData` [#setdata]

```typescript
function setData(
    el: HTMLElement,
    data: Record<string, string | number | boolean | null | undefined>,
): void
```

### `sideRail` [#siderail]

The shell's sidebar, for a badge on an entry: `sideRail(ctx)?.setBadge(id, count)`.

Also exported from `@luxalgo/vela-pro/plugin`.

```typescript
function sideRail(ctx: WidgetContext): SidebarControl | null
```

From `@luxalgo/vela/plugin`: `SidebarControl`, `WidgetContext`.

## Classes [#classes]

### `Disposer` [#disposer]

Drop every listener registered through `listen` at once: a surface's teardown.

Also exported from `@luxalgo/vela-pro/plugin`.

```typescript
class Disposer {
    add(fn: () => void): void;
    listen<K extends keyof WindowEventMap>(
        target: Window,
        type: K,
        fn: (e: WindowEventMap[K]) => void,
        opts?: AddEventListenerOptions | boolean,
    ): void;
    listen<K extends keyof DocumentEventMap>(
        target: Document,
        type: K,
        fn: (e: DocumentEventMap[K]) => void,
        opts?: AddEventListenerOptions | boolean,
    ): void;
    listen<K extends keyof HTMLElementEventMap>(
        target: HTMLElement,
        type: K,
        fn: (e: HTMLElementEventMap[K]) => void,
        opts?: AddEventListenerOptions | boolean,
    ): void;
    listen(
        target: EventTarget,
        type: string,
        fn: EventListener,
        opts?: AddEventListenerOptions | boolean,
    ): void;
    dispose(): void;
}
```

## Interfaces and types [#interfaces-and-types]

### `BottomDockHandle` [#bottomdockhandle]

Drive a shell's dock from code (a panel opening itself when a strategy runs).

```typescript
interface BottomDockHandle {
    readonly isOpen: boolean;
    readonly active: string | null;
    open(id?: string): void;
    close(): void;
    toggle(id: string): void;
    setMaximized(on: boolean): void;
    onChange(cb: () => void): () => void;
}
```

| Member           | Type                             | Description                                                            |
| ---------------- | -------------------------------- | ---------------------------------------------------------------------- |
| `isOpen`         | `boolean`                        |                                                                        |
| `active`         | `string \| null`                 |                                                                        |
| `open()`         | `(id?: string) => void`          |                                                                        |
| `close()`        | `() => void`                     |                                                                        |
| `toggle()`       | `(id: string) => void`           | The rail's press: open on `id`, or close when `id` is already showing. |
| `setMaximized()` | `(on: boolean) => void`          |                                                                        |
| `onChange()`     | `(cb: () => void) => () => void` |                                                                        |

### `BottomPanelDescriptor` [#bottompaneldescriptor]

```typescript
interface BottomPanelDescriptor {
    id: string;
    title: MessageLike;
    icon: string;
    description?: MessageLike;
    order?: number;
    rail?: boolean;
    restoreOpen?: boolean;
    minHeight?: number;
    collapseBelow?: number;
    chrome?: 'header' | 'none';
    mount(ctx: WidgetContext, body: HTMLElement, header: BottomPanelHeader): BottomPanelHandle | void;
}
```

| Member           | Type                                                                                              | Description                                                                                                                                                              |
| ---------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`             | `string`                                                                                          | Stable id: the key the open panel persists under.                                                                                                                        |
| `title`          | `MessageLike`                                                                                     |                                                                                                                                                                          |
| `icon`           | `string`                                                                                          |                                                                                                                                                                          |
| `description?`   | `MessageLike`                                                                                     | Rail hover-card text.                                                                                                                                                    |
| `order?`         | `number`                                                                                          | Rail order (ascending, default 100).                                                                                                                                     |
| `rail?`          | `boolean`                                                                                         | A rail button toggles the panel (default true). False for a panel that opens itself: the strategy tester, when a strategy reports a backtest.                            |
| `restoreOpen?`   | `boolean`                                                                                         | Reopen the dock on this panel when the saved state had it open (default: what `rail` says). False for a panel that opens itself.                                         |
| `minHeight?`     | `number`                                                                                          | The dock's floor while this panel shows, px (default: the dock's `minHeight`).                                                                                           |
| `collapseBelow?` | `number`                                                                                          | Released from a drag below this height, the dock snaps down to the panel's floor.                                                                                        |
| `chrome?`        | `'header' \| 'none'`                                                                              | `'header'` (default): the dock draws a title bar with maximize and close. `'none'`: the panel draws its own header in the body it is handed (tabs in it, its own close). |
| `mount()`        | `(ctx: WidgetContext, body: HTMLElement, header: BottomPanelHeader) => BottomPanelHandle \| void` | Mounted once per shell, when the dock mounts, so a panel can listen while hidden.                                                                                        |

See also: [`BottomPanelHandle`](/vela-pro/api/layout#bottompanelhandle), [`BottomPanelHeader`](/vela-pro/api/layout#bottompanelheader). From `@luxalgo/vela/plugin`: `MessageLike`, `WidgetContext`.

### `BottomPanelHandle` [#bottompanelhandle]

```typescript
interface BottomPanelHandle {
    onOpen?(): void;
    onClose?(): void;
    destroy?(): void;
}
```

| Member       | Type         | Description                                                        |
| ------------ | ------------ | ------------------------------------------------------------------ |
| `onOpen?()`  | `() => void` | The panel became the visible tab of an open dock.                  |
| `onClose?()` | `() => void` | The panel stopped being visible (another tab, or the dock closed). |
| `destroy?()` | `() => void` |                                                                    |

### `BottomPanelHeader` [#bottompanelheader]

The chrome a bottom panel shares with the dock.

Also exported from `@luxalgo/vela-pro/plugin`.

```typescript
interface BottomPanelHeader {
    readonly slot: HTMLElement;
    setCount(count: number | null): void;
    close(): void;
    isMaximized(): boolean;
    setMaximized(on: boolean): void;
    fold(height: number | null): void;
}
```

| Member           | Type                               | Description                                                                                                                                                        |
| ---------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `slot`           | `HTMLElement`                      | Controls shown at the header's right while this panel is the active tab.                                                                                           |
| `setCount()`     | `(count: number \| null) => void`  | A count beside the panel's title (open positions, trades); null hides it.                                                                                          |
| `close()`        | `() => void`                       | Close the dock: what a panel drawing its own header wires its close button to.                                                                                     |
| `isMaximized()`  | `() => boolean`                    |                                                                                                                                                                    |
| `setMaximized()` | `(on: boolean) => void`            | Fill the shell with the dock, or give the charts their room back.                                                                                                  |
| `fold()`         | `(height: number \| null) => void` | Fold the dock to exactly `height` px (a one-line header) while this panel shows, with no resize edge; `null` unfolds it back to the height the user dragged it to. |

### `Child` [#child]

```typescript
type Child = Node | string | number | null | undefined | false | readonly Child[];
```

### `DockHeightLimits` [#dockheightlimits]

```typescript
interface DockHeightLimits {
    min: number;
    shell: number;
    chartFloor: number;
}
```

| Member       | Type     | Description                                        |
| ------------ | -------- | -------------------------------------------------- |
| `min`        | `number` | The dock's own floor (its header plus a few rows). |
| `shell`      | `number` | The shell's height.                                |
| `chartFloor` | `number` | What the charts keep, at least, above the dock.    |

### `DockState` [#dockstate]

```typescript
interface DockState {
    open: boolean;
    active: string | null;
}
```

### `ElementProps` [#elementprops]

```typescript
interface ElementProps {
    class?: string;
    part?: string;
    data?: Record<string, string | number | boolean | null | undefined>;
    attrs?: Record<string, string | number | boolean | null | undefined>;
    style?: Partial<CSSStyleDeclaration> | string;
    text?: string;
    title?: string;
    on?: { [K in keyof HTMLElementEventMap]?: (e: HTMLElementEventMap[K]) => void };
}
```

| Member   | Type                                                                         | Description                                                                        |
| -------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `class?` | `string`                                                                     | Space-separated class list.                                                        |
| `part?`  | `string`                                                                     | The styling hook: `data-part="…"`.                                                 |
| `data?`  | `Record<string, string \| number \| boolean \| null \| undefined>`           | `data-*` attributes (`{ side: 'buy' }` → `data-side="buy"`); null/false drops one. |
| `attrs?` | `Record<string, string \| number \| boolean \| null \| undefined>`           | Plain attributes; null/false drops one, true writes an empty one.                  |
| `style?` | `Partial<CSSStyleDeclaration> \| string`                                     |                                                                                    |
| `text?`  | `string`                                                                     |                                                                                    |
| `title?` | `string`                                                                     |                                                                                    |
| `on?`    | `{ [K in keyof HTMLElementEventMap]?: (e: HTMLElementEventMap[K]) => void }` |                                                                                    |

### `RailHint` [#railhint]

Hover-card copy for a rail entry (a side panel or an item).

```typescript
interface RailHint {
    description?: MessageLike;
    shortcut?: string;
}
```

From `@luxalgo/vela/plugin`: `MessageLike`.

### `RailItemDescriptor` [#railitemdescriptor]

```typescript
interface RailItemDescriptor {
    id: string;
    title: MessageLike;
    icon: string;
    description?: MessageLike;
    shortcut?: string;
    order?: number;
    run(ctx: WidgetContext): void;
    active?(ctx: WidgetContext): boolean;
    subscribe?(ctx: WidgetContext, refresh: () => void): () => void;
}
```

| Member         | Type                                                      | Description                                                         |
| -------------- | --------------------------------------------------------- | ------------------------------------------------------------------- |
| `id`           | `string`                                                  | Stable id: what a host lists in `top`/`bottom`, and what hides it.  |
| `title`        | `MessageLike`                                             |                                                                     |
| `icon`         | `string`                                                  |                                                                     |
| `description?` | `MessageLike`                                             | Hover-card text.                                                    |
| `shortcut?`    | `string`                                                  | A shortcut shown on the hover card (`Alt+T`).                       |
| `order?`       | `number`                                                  | Sort key within the `'items'` flow slot (ascending, default 100).   |
| `run()`        | `(ctx: WidgetContext) => void`                            |                                                                     |
| `active?()`    | `(ctx: WidgetContext) => boolean`                         | Pressed look (a toggle that is on).                                 |
| `subscribe?()` | `(ctx: WidgetContext, refresh: () => void) => () => void` | Re-read `active` when the item's own state changes: call `refresh`. |

From `@luxalgo/vela/plugin`: `MessageLike`, `WidgetContext`.

## Constants [#constants]

### `PRO_UI_STYLE_ID` [#pro_ui_style_id]

```typescript
const PRO_UI_STYLE_ID: 'vela-pro-ui';
```
