@stocksharp/trading-controls 0.1.0

package/src/positions-widget.ts

@@ -0,0 +1,305 @@
+// Positions — multi-instance.
+//
+// Builds its own DOM (see `_buildRoot`) rather than cloning a <template> out of
+// the page it happens to be rendered on, so it can be constructed by any host
+// that supplies a `TradingHost`. Every instance shares the same data source
+// (the host's refresh / a position update off the socket); the host broadcasts
+// each update to every live instance so duplicates of the panel render in
+// lockstep.
+//
+// The table is `DataGrid` from `@stocksharp/grids`: the columns below are this
+// blotter's single declaration and the <thead> is left empty for the grid to
+// fill. The cash balance is a pinned row — a different shape from a position,
+// so it supplies its own cells, sits outside the sort and stays out of the
+// exported sheet.
+import { formatPnl, formatPrice } from './formatters.js';
+import { makeElement, makeIconButton, makePanelId, makePanelRoot } from './dom.js';
+import { ControlTypes } from './control-types.js';
+import { TradingHost, assertHost } from './trading-host.js';
+import type { BalanceRow, PositionRow } from './trading-data.js';
+import { DataGrid, GridColumn, GridPinnedRow, GridPinnedPlacements } from '@stocksharp/grids/source/data-grid';
+
+/// Everything the blotter needs beyond the host port. All required: the action
+/// buttons live in the cells and in the rail now, so a panel that cannot
+/// close, reverse or reload a position is not this panel.
+export interface PositionsDeps {
+    host: TradingHost;
+    closePosition(portfolioId: number, instrumentId: number, symbol: string): void;
+    reversePosition(portfolioId: number, instrumentId: number, symbol: string): void;
+    refreshPositions(): void;
+}
+
+export class PositionsWidget {
+    static TYPE = ControlTypes.Positions;
+
+    rootEl: HTMLElement;
+    el: HTMLElement | null;
+    // Comment style is `//` on purpose below the public members: the declaration
+    // emitter keeps a private member's doc comment while dropping its body, so a
+    // `///` here would reattach to the next public member in the API snapshot.
+    _host: TradingHost;
+    _deps: PositionsDeps;
+    _closeBtn: HTMLElement | null;
+    _refreshBtn: HTMLElement | null;
+    _exportBtn: HTMLElement | null;
+    _positions: PositionRow[];
+    _balance: BalanceRow | null;
+    _grid: DataGrid<PositionRow> | null;
+
+    static create(hostEl: HTMLElement, state: Record<string, unknown>, deps: PositionsDeps): PositionsWidget {
+        // Assert before building: the markup below is localized through the
+        // host, so a missing host has to fail here rather than render a panel
+        // captioned with raw English keys.
+        const host = assertHost(deps?.host, 'PositionsWidget');
+        const root = PositionsWidget._buildRoot(host);
+        root.id = makePanelId(PositionsWidget.TYPE);
+        hostEl.appendChild(root);
+        return new PositionsWidget(root, state || {}, deps);
+    }
+
+    // The panel's markup. The host stylesheet reads this structure, and a
+    // docking host lifts `.panel-header`'s children into its tab strip.
+    //
+    // The rail's refresh button is the one thing that could not come across
+    // unchanged from the terminal's Razor template: it used to be an inline
+    // `onclick="terminalApp.refreshPositions()"`, which is a reference to a
+    // global this control must not have. It carries `.panel-refresh-btn` now —
+    // the name the trade-history rail already gave the identical button — and
+    // is wired to the `refreshPositions` dep.
+    static _buildRoot(host: TradingHost): HTMLElement {
+        const title = host.t('OpenPositions');
+        return makePanelRoot('positions-panel', title, [
+            makeElement('div', 'panel-header', {}, [
+                makeElement('span', '', {}, [host.t('Positions')]),
+                makeIconButton('bt-icon-btn bt-icon-cancel panel-close-btn', host.t('ClosePanel'), 'bi-x', { type: 'button' }),
+            ]),
+            makeElement('div', 'panel-body panel-body-with-rail', {}, [
+                makeElement('div', 'panel-body-content', {}, [
+                    makeElement('table', 'terminal-table positions-table', { role: 'table', 'aria-label': title }, [
+                        makeElement('thead', '', {}, []),
+                        makeElement('tbody', 'positions-body', {}, []),
+                    ]),
+                ]),
+                makeElement('div', 'panel-rail', { role: 'toolbar', 'aria-label': host.t('PositionsActions') }, [
+                    makeIconButton('bt-icon-btn panel-refresh-btn', host.t('Refresh'), 'bi-arrow-clockwise', {}),
+                    makeIconButton('bt-icon-btn panel-export-btn', host.t('ExportToExcel'), 'bi-file-earmark-spreadsheet', {}),
+                ]),
+            ]),
+        ]);
+    }
+
+    constructor(rootEl: HTMLElement, _state: Record<string, unknown>, deps: PositionsDeps) {
+        this._host = assertHost(deps?.host, 'PositionsWidget');
+        for (const name of ['closePosition', 'reversePosition', 'refreshPositions'] as const) {
+            if (typeof deps?.[name] !== 'function')
+                throw new Error(`PositionsWidget: dep "${name}" is required`);
+        }
+
+        this.rootEl = rootEl;
+        this._deps = deps;
+        this.el = this.rootEl.querySelector('.positions-body');
+        this._closeBtn = this.rootEl.querySelector('.panel-close-btn');
+        this._refreshBtn = this.rootEl.querySelector('.panel-refresh-btn');
+        this._exportBtn = this.rootEl.querySelector('.panel-export-btn');
+        this._positions = [];
+        this._balance = null;
+
+        this._closeBtn?.addEventListener('click', (e) => {
+            e.preventDefault();
+            this._host.close();
+        });
+
+        this._refreshBtn?.addEventListener('click', (e) => {
+            e.preventDefault();
+            this._deps.refreshPositions();
+        });
+
+        this._exportBtn?.addEventListener('click', (e) => {
+            e.preventDefault();
+            this._export();
+        });
+
+        const head = this.rootEl.querySelector('.positions-table thead');
+        this._grid = head && this.el
+            ? new DataGrid<PositionRow>({
+                head: head as HTMLElement,
+                body: this.el,
+                columns: this._columns(),
+                // Alphabetical by instrument at rest — a stable, predictable order (positions have no
+                // natural "newest") the user can scan by symbol.
+                defaultSort: { col: 'instrument', dir: 'asc' },
+                // Same identity applyDelta matches on: id alone isn't unique (id=0 for
+                // unsaved snapshots), and a portfolio can hold one position per instrument.
+                rowKey: (p) => PositionsWidget._key(p),
+                emptyText: this._host.t('No positions'),
+                // Re-read on every render, so the cash figures track the live balance
+                // without the widget having to repaint the position rows itself.
+                pinnedRows: () => this._pinnedRows(),
+            })
+            : null;
+
+        this._host.register(this);
+
+        // If the host already has a positions snapshot it will broadcast it on
+        // demand; new instances start empty until the first refresh tick.
+    }
+
+    dispose(): void {
+        this._host.unregister(this);
+        try { this.rootEl.remove(); } catch { /* already detached */ }
+    }
+
+    update(positions: PositionRow[]): void {
+        this._positions = positions || [];
+        this._grid?.setRows(this._positions);
+    }
+
+    /// Null clears the pinned row — which is not the same as an all-zero
+    /// balance, and reads differently: no row at all versus a row of zeros.
+    updateBalance(balance: BalanceRow | null): void {
+        this._balance = balance;
+        this._grid?.render();
+    }
+
+    /// Apply a single position delta. Match by (portfolioId, instrumentId) — id
+    /// alone isn't unique (id=0 for unsaved snapshots). Quantity hitting zero
+    /// closes the row.
+    applyDelta(position: PositionRow): void {
+        if (!position) return;
+        const idx = this._positions.findIndex(p =>
+            p.portfolioId === position.portfolioId &&
+            ((position.instrumentId != null && p.instrumentId === position.instrumentId) ||
+             (position.instrumentId == null && p.instrument === position.instrument)));
+        const closed = (position.quantity || 0) === 0;
+
+        if (idx >= 0) {
+            if (closed) this._positions.splice(idx, 1);
+            else this._positions[idx] = { ...this._positions[idx], ...position };
+        } else if (!closed) {
+            this._positions.push(position);
+        }
+        this.update(this._positions);
+    }
+
+    // Export the table to .xlsx in the currently rendered (sorted) order. The
+    // balance summary is a pinned row — a different shape from a position — so
+    // the grid keeps it out of the sheet.
+    _export(): void {
+        this._grid?.download('positions', this._host.t('Positions'));
+    }
+
+    // The blotter's single column declaration: what the header says, what the
+    // grid sorts on, what the cell shows, how it is coloured, and what reaches
+    // the exported sheet. Prices are formatted on screen but exported raw, so
+    // the sheet stays numeric.
+    _columns(): GridColumn<PositionRow>[] {
+        const label = (key: string) => this._host.t(key);
+        return [
+            {
+                key: 'instrument',
+                header: label('Symbol'),
+                exportable: true,
+                value: (p) => p.instrument,
+            },
+            {
+                key: 'quantity',
+                header: label('Qty'),
+                exportable: true,
+                value: (p) => p.quantity,
+                cellClass: (p) => ((p.quantity ?? 0) > 0 ? 'side-buy' : 'side-sell'),
+            },
+            {
+                key: 'avgPrice',
+                header: label('AvgPrice'),
+                exportable: true,
+                value: (p) => p.avgPrice,
+                render: (p) => formatPrice(p.avgPrice),
+            },
+            {
+                key: 'currentPrice',
+                header: label('Current'),
+                exportable: true,
+                value: (p) => p.currentPrice,
+                render: (p) => formatPrice(p.currentPrice),
+            },
+            {
+                key: 'pnl',
+                header: label('PnL'),
+                exportable: true,
+                value: (p) => PositionsWidget._totalPnl(p),
+                render: (p) => formatPnl(PositionsWidget._totalPnl(p)),
+                cellClass: (p) => this._host.presentation.pnlClass(PositionsWidget._totalPnl(p)),
+            },
+            {
+                key: 'actions',
+                header: label('Actions'),
+                headerHidden: true,
+                exportable: false,
+                cellClass: () => 'position-actions',
+                render: (p) => this._actionButtons(p),
+            },
+        ];
+    }
+
+    // The cash balance, pinned above the positions. It does not share the shape
+    // the position columns read, so it supplies its own cells; it is not a row
+    // of data, so it is neither sorted nor exported. Being content, it also
+    // suppresses the "no positions" row — a table showing a balance is not empty.
+    _pinnedRows(): GridPinnedRow[] {
+        const balance = this._balance;
+        if (!balance) return [];
+
+        const fmt = (v: number | null | undefined) => (v || 0).toLocaleString(undefined, { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+        return [{
+            key: 'balance',
+            className: 'balance-row',
+            place: GridPinnedPlacements.Top,
+            cells: [
+                { content: this._host.t('USD'), className: 'balance-ccy' },
+                { content: '$' + fmt(balance.available), className: 'balance-available' },
+                { content: this._host.t('Locked: ${0}', fmt(balance.locked)), className: 'balance-locked' },
+                { content: '', className: '' },
+                { content: '$' + fmt(balance.total), className: 'balance-total' },
+            ],
+        }];
+    }
+
+    // Realized and unrealized together — what the PnL column shows, sorts and
+    // exports, so the three cannot drift apart.
+    static _totalPnl(position: PositionRow): number {
+        return (position.unrealizedPnl || 0) + (position.realizedPnl || 0);
+    }
+
+    static _key(position: PositionRow): string {
+        return `${position.portfolioId}:${position.instrumentId ?? position.instrument}`;
+    }
+
+    // Close and reverse, wired to the controller through deps. Real buttons with
+    // their own listeners — the symbol used to be interpolated into an inline
+    // onclick attribute, which is why it needed quote-escaping first.
+    _actionButtons(position: PositionRow): Node {
+        const cell = document.createDocumentFragment();
+        cell.appendChild(this._actionButton(
+            'bt-icon-cancel', 'bi-x-circle',
+            this._host.t('Close position'), this._host.t('Close position on {0}', position.instrument),
+            () => this._deps.closePosition(position.portfolioId!, position.instrumentId!, position.instrument!)));
+        cell.appendChild(this._actionButton(
+            'bt-icon-reverse', 'bi-arrow-left-right',
+            this._host.t('Reverse position'), this._host.t('Reverse position on {0}', position.instrument),
+            () => this._deps.reversePosition(position.portfolioId!, position.instrumentId!, position.instrument!)));
+        return cell;
+    }
+
+    _actionButton(styleClass: string, iconClass: string, title: string, label: string, onClick: () => void): HTMLButtonElement {
+        const button = document.createElement('button');
+        button.type = 'button';
+        button.className = `bt-icon-btn ${styleClass}`;
+        button.title = title;
+        button.setAttribute('aria-label', label);
+        const icon = document.createElement('i');
+        icon.className = `bi ${iconClass}`;
+        button.appendChild(icon);
+        button.addEventListener('click', onClick);
+        return button;
+    }
+}

package/src/trade-history-widget.ts

@@ -0,0 +1,221 @@
+// Trade history — multi-instance.
+//
+// Read-only table of executed trades for the active portfolio. Builds its own
+// DOM (see `_buildRoot`) rather than cloning a <template> out of the page, so
+// it can be constructed by any host that supplies a `TradingHost`.
+//
+// Which portfolio to load and what to load it through both come off the host's
+// trading context rather than being read out of a singleton here: the panel
+// renders what it is given, and the host decides what "the active portfolio"
+// means.
+//
+// The table is `DataGrid` from `@stocksharp/grids`: the columns below are this
+// blotter's single declaration and the <thead> is left empty for the grid to
+// fill.
+import { formatPrice, formatQty, formatTime } from './formatters.js';
+import { makeElement, makeIconButton, makePanelId, makePanelRoot } from './dom.js';
+import { ControlTypes } from './control-types.js';
+import { TradingHost, assertHost } from './trading-host.js';
+import type { TradeRow } from './trading-data.js';
+import { DataGrid, GridColumn } from '@stocksharp/grids/source/data-grid';
+
+/// The panel needs nothing beyond the host port: its data source, its
+/// portfolio and its lifecycle all arrive through it.
+export interface TradeHistoryDeps {
+    host: TradingHost;
+}
+
+export class TradeHistoryWidget {
+    static TYPE = ControlTypes.TradeHistory;
+
+    rootEl: HTMLElement;
+    bodyEl: HTMLElement | null;
+    // `//` rather than `///` from here down — see the note in positions-widget.
+    _host: TradingHost;
+    _closeBtn: HTMLElement | null;
+    _refreshBtn: HTMLElement | null;
+    _exportBtn: HTMLElement | null;
+    _rows: TradeRow[];
+    _grid: DataGrid<TradeRow> | null;
+
+    static create(hostEl: HTMLElement, state: Record<string, unknown>, deps: TradeHistoryDeps): TradeHistoryWidget {
+        // Assert before building: the markup below is localized through the
+        // host, so a missing host has to fail here rather than render a panel
+        // captioned with raw English keys.
+        const host = assertHost(deps?.host, 'TradeHistoryWidget');
+        const root = TradeHistoryWidget._buildRoot(host);
+        root.id = makePanelId(TradeHistoryWidget.TYPE);
+        hostEl.appendChild(root);
+        return new TradeHistoryWidget(root, state || {}, deps);
+    }
+
+    // The panel's markup. The host stylesheet reads this structure, and a
+    // docking host lifts `.panel-header`'s children into its tab strip.
+    static _buildRoot(host: TradingHost): HTMLElement {
+        const title = host.t('TradeHistory');
+        return makePanelRoot('trade-history-panel', title, [
+            makeElement('div', 'panel-header', {}, [
+                makeElement('span', '', {}, [title]),
+                makeIconButton('bt-icon-btn bt-icon-cancel panel-close-btn', host.t('ClosePanel'), 'bi-x', { type: 'button' }),
+            ]),
+            makeElement('div', 'panel-body panel-body-with-rail', {}, [
+                makeElement('div', 'panel-body-content', {}, [
+                    makeElement('table', 'terminal-table trade-history-table', { role: 'table', 'aria-label': host.t('TradeHistoryList') }, [
+                        makeElement('thead', '', {}, []),
+                        makeElement('tbody', 'trade-history-body', {}, []),
+                    ]),
+                ]),
+                makeElement('div', 'panel-rail', { role: 'toolbar', 'aria-label': host.t('TradeHistoryActions') }, [
+                    makeIconButton('bt-icon-btn panel-refresh-btn', host.t('Refresh'), 'bi-arrow-clockwise', {}),
+                    makeIconButton('bt-icon-btn panel-export-btn', host.t('ExportToExcel'), 'bi-file-earmark-spreadsheet', {}),
+                ]),
+            ]),
+        ]);
+    }
+
+    constructor(rootEl: HTMLElement, _state: Record<string, unknown>, deps: TradeHistoryDeps) {
+        this._host = assertHost(deps?.host, 'TradeHistoryWidget');
+
+        this.rootEl = rootEl;
+        this.bodyEl = this.rootEl.querySelector('.trade-history-body');
+        this._closeBtn = this.rootEl.querySelector('.panel-close-btn');
+        this._refreshBtn = this.rootEl.querySelector('.panel-refresh-btn');
+        this._exportBtn = this.rootEl.querySelector('.panel-export-btn');
+
+        this._closeBtn?.addEventListener('click', (e) => {
+            e.preventDefault();
+            this.dispose();
+            this._host.close();
+        });
+        this._refreshBtn?.addEventListener('click', (e) => {
+            e.preventDefault();
+            void this.refresh();
+        });
+
+        this._exportBtn?.addEventListener('click', (e) => {
+            e.preventDefault();
+            this._export();
+        });
+
+        this._rows = [];
+
+        const head = this.rootEl.querySelector('.trade-history-table thead');
+        this._grid = head && this.bodyEl
+            ? new DataGrid<TradeRow>({
+                head: head as HTMLElement,
+                body: this.bodyEl,
+                columns: this._columns(),
+                // Most recent fill on top by default — the natural way to read a trade blotter.
+                defaultSort: { col: 'time', dir: 'desc' },
+                rowKey: (t) => String(t.id),
+                emptyText: this._host.t('No trade history'),
+            })
+            : null;
+
+        this._host.register(this);
+    }
+
+    dispose(): void {
+        this._host.unregister(this);
+        try { this.rootEl.remove(); } catch { /* already detached */ }
+    }
+
+    /// Reload against whichever portfolio the host says is active right now.
+    ///
+    /// Two guards, and they are not the same one. No portfolio means there is
+    /// nothing to show — a guest session has none. A portfolio the host will
+    /// not `allow` reading means the session cannot make the call at all: this
+    /// is somebody's executed trades, so a page that has a portfolio id lying
+    /// around but no live credential must not fire the request and collect a
+    /// 401 for it. The panel asks the host rather than inspecting a token,
+    /// because what counts as a usable session is the host's to know.
+    ///
+    /// Order matters: the portfolio check runs first, so a session with no
+    /// portfolio is simply quiet — `allow` is the one that may put a sign-in
+    /// prompt on screen, and reaching it means the page did have an account to
+    /// load.
+    async refresh(): Promise<void> {
+        const pf = this._host.trading.portfolioId();
+        if (!pf || !this._grid) return;
+        if (!this._host.allow('load trade history')) return;
+        try {
+            this._rows = await this._host.trading.api.getExecutions(pf, null, 200) || [];
+            this._grid.setRows(this._rows);
+        } catch (err) {
+            // Through the port, not the console: this is the diagnostic the
+            // user cannot see and support has to, and routing it here is also
+            // what makes it assertable.
+            this._host.log(`TradeHistoryWidget: failed to load trade history: ${err}`);
+        }
+    }
+
+    // Export the table to .xlsx in the currently rendered (sorted) order.
+    _export(): void {
+        this._grid?.download('trades', this._host.t('TradeHistory'));
+    }
+
+    // The blotter's single column declaration. The two id columns read `#42` on
+    // screen and export the bare number, so the sheet stays sortable as a number.
+    _columns(): GridColumn<TradeRow>[] {
+        // `label`, not `t` — every row lambda below already binds `t` as the
+        // trade it is rendering, and a translator sharing that name would be
+        // shadowed inside exactly the callbacks that read it.
+        const label = (key: string) => this._host.t(key);
+        const presentation = this._host.presentation;
+        return [
+            {
+                key: 'id',
+                header: label('ID'),
+                exportable: true,
+                value: (t) => t.id,
+                render: (t) => '#' + t.id,
+                cellClass: () => 'mono-id',
+            },
+            {
+                key: 'time',
+                header: label('Time'),
+                exportable: true,
+                value: (t) => t.executedAt || t.time,
+                render: (t) => formatTime(t.executedAt || t.time),
+                exportValue: (t) => formatTime(t.executedAt || t.time),
+            },
+            {
+                key: 'symbol',
+                header: label('Sym'),
+                exportable: true,
+                value: (t) => t.instrumentSymbol || t.symbol,
+            },
+            {
+                key: 'side',
+                header: label('Side'),
+                exportable: true,
+                value: (t) => t.side,
+                render: (t) => presentation.sideText(t.side!),
+                cellClass: (t) => presentation.sideClass(t.side!),
+                exportValue: (t) => presentation.sideText(t.side!),
+            },
+            {
+                key: 'quantity',
+                header: label('Qty'),
+                exportable: true,
+                value: (t) => t.quantity,
+                render: (t) => formatQty(t.quantity),
+            },
+            {
+                key: 'price',
+                header: label('Price'),
+                exportable: true,
+                value: (t) => t.price,
+                render: (t) => formatPrice(t.price),
+            },
+            {
+                key: 'order',
+                header: label('Order'),
+                exportable: true,
+                value: (t) => t.order || t.orderId,
+                render: (t) => '#' + (t.order || t.orderId || ''),
+                cellClass: () => 'mono-id',
+            },
+        ];
+    }
+}

package/src/trading-data.ts

@@ -0,0 +1,121 @@
+// The rows the controls render.
+//
+// These are wire shapes, not domain models: the host fetches them from
+// whatever backend it has and hands them over, and this package only reads
+// them. That is why every field is optional. A server that omits `realizedPnl`
+// on a flat position, a snapshot row that predates a field, an optimistic
+// client-side insert carrying half a fill — all of them are ordinary here, and
+// every control already guards with `?? 0` / `|| ''` at the point of use. A
+// required field would only move that guard to the host, which cannot honour it
+// either.
+//
+// Two fields are deliberately unions rather than enums. `side` and `status`
+// arrive in more than one spelling depending on which endpoint produced the row
+// (a numeric StockSharp enum from the socket, a name from the DTO, an uppercase
+// name from the history endpoint), and normalising them is the host's job —
+// `TradingPresentation` is where that knowledge lives. Narrowing the type here
+// would only force a cast at every call site that is already correct.
+//
+// Every numeric field is `number | null` as well as optional, for the same
+// reason: an absent price reaches us as an omitted key from one endpoint and as
+// an explicit null from another, both meaning "not set". Saying so once here is
+// what lets the read sites stay the plain `?? 0` / `|| ''` they already were.
+//
+// This module has no imports and no behaviour.
+
+/// Buy or sell, in any of the spellings the wire uses: `0`/`1`, `'Buy'`/`'Sell'`
+/// or `'BUY'`/`'SELL'`.
+export type OrderSide = number | string;
+
+/// A StockSharp `OrderTypes` value (`0` limit, `1` market, `2` conditional) or
+/// its name.
+export type OrderType = number | string;
+
+/// A StockSharp `OrderStates` value (see `OrderStates` in
+/// `active-orders-widget.ts`) or its name.
+export type OrderStatus = number | string;
+
+/// One open position in a portfolio.
+export interface PositionRow {
+    portfolioId?: number | null;
+    /// Numeric instrument id where the source has one. Rows from an unsaved
+    /// snapshot may carry only `instrument`, which is why the identity used for
+    /// matching falls back to it.
+    instrumentId?: number | null;
+    instrument?: string;
+    quantity?: number | null;
+    avgPrice?: number | null;
+    currentPrice?: number | null;
+    unrealizedPnl?: number | null;
+    realizedPnl?: number | null;
+}
+
+/// The cash side of a portfolio, rendered as a pinned row above the positions.
+export interface BalanceRow {
+    available?: number | null;
+    locked?: number | null;
+    total?: number | null;
+}
+
+/// One live or recently terminal order.
+export interface OrderRow {
+    /// The register transaction id. This is what cancel, replace and inline edit
+    /// address an order by, and what the grid keys rows on.
+    id?: number | null;
+    /// Per-user friendly counter shown in the ID column. Absent on rows cached
+    /// from before the counter shipped.
+    localId?: number | null;
+    instrument?: string;
+    side?: OrderSide;
+    type?: OrderType;
+    quantity?: number | null;
+    /// The unfilled remainder. A control that shows what is still resting on
+    /// the book reads this and falls back to `quantity` — a snapshot row taken
+    /// before anything filled carries only the latter.
+    balance?: number | null;
+    limitPrice?: number | null;
+    stopPrice?: number | null;
+    status?: OrderStatus;
+    /// Venue text for a rejection. Some adapters wrap it in a JSON blob — see
+    /// `cleanRejectReason`.
+    rejectReason?: string;
+}
+
+/// One executed trade.
+export interface TradeRow {
+    id?: number | null;
+    /// Execution time. `executedAt` is what the API returns; `time` is what a
+    /// socket fill carries, and the control reads whichever is present.
+    executedAt?: string;
+    time?: string;
+    instrumentSymbol?: string;
+    symbol?: string;
+    side?: OrderSide;
+    quantity?: number | null;
+    price?: number | null;
+    /// The order this fill belongs to, under either of the two names the
+    /// endpoints use.
+    order?: number | null;
+    orderId?: number | null;
+}
+
+/// One tradable instrument, as the instrument search returns it.
+export interface InstrumentRow {
+    /// Qualified symbol — `BTC@IMEX`. The display form drops the venue.
+    symbol?: string;
+    name?: string;
+    exchange?: string;
+    /// Admin-assigned grouping. The watchlist turns the distinct values into
+    /// filter tabs, so the tab set is configured rather than hardcoded.
+    category?: string;
+}
+
+/// What a control has computed about a symbol from the live tape. Handed to the
+/// host's ticker sink as-is.
+export interface QuoteStats {
+    lastPrice?: number | null;
+    /// First price observed this session-day, the change percentage is measured
+    /// from.
+    baseline?: number | null;
+    chgPct?: number | null;
+}