@stocksharp/trading-controls 0.1.0

package/src/active-orders-widget.ts

@@ -0,0 +1,411 @@
+// Active orders — multi-instance.
+//
+// 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`.
+// Every instance shares the same data source (a host refresh / an order update
+// off the socket); each update fans through the host's broadcast so duplicates
+// stay in sync.
+//
+// The table itself is `DataGrid` from `@stocksharp/grids`: the columns below are
+// the single declaration of this blotter — caption, value, rendering, colour
+// class and export all live together, and the <thead> is left empty for the
+// grid to fill. Cells that hold a control return a real Node with its own
+// listener, so nothing here reaches a global through an inline onclick
+// attribute; the callbacks arrive as deps instead.
+import { cleanRejectReason, formatPrice, formatQty } 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 { OrderRow } from './trading-data.js';
+import { DataGrid, GridColumn } from '@stocksharp/grids/source/data-grid';
+
+/// StockSharp order states as they arrive on the wire. The blotter branches on
+/// them for row colour, for whether a cell can be edited in place and for what
+/// the × button does, so they are named once here instead of appearing as bare
+/// numbers at each branch.
+export const OrderStates = {
+    PendingRisk: 1,
+    Sent: 2,
+    Active: 3,
+    PartiallyFilled: 4,
+    Filled: 5,
+    Rejected: 6,
+    Cancelled: 7,
+} as const;
+
+/// What the blotter needs beyond the host port. All required: a panel that
+/// cannot cancel, modify or reload its orders is not this panel.
+export interface ActiveOrdersDeps {
+    host: TradingHost;
+    cancelOrder(orderId: number): void;
+    dismissOrder(orderId: number): void;
+    editOrderField(orderId: number, field: string): void;
+    replaceOrder(orderId: number, quantity: number, limitPrice: number, stopPrice: number): void;
+    cancelAllOrders(): void;
+    refreshOrders(): void;
+}
+
+export class ActiveOrdersWidget {
+    static TYPE = ControlTypes.ActiveOrders;
+
+    rootEl: HTMLElement;
+    el: HTMLElement | null;
+    // `//` rather than `///` from here down — see the note in positions-widget.
+    _host: TradingHost;
+    _deps: ActiveOrdersDeps;
+    _closeBtn: HTMLElement | null;
+    _cancelAllBtn: HTMLElement | null;
+    _refreshBtn: HTMLElement | null;
+    _exportBtn: HTMLElement | null;
+    _orders: OrderRow[];
+    _grid: DataGrid<OrderRow> | null;
+
+    static create(hostEl: HTMLElement, state: Record<string, unknown>, deps: ActiveOrdersDeps): ActiveOrdersWidget {
+        // 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, 'ActiveOrdersWidget');
+        const root = ActiveOrdersWidget._buildRoot(host);
+        root.id = makePanelId(ActiveOrdersWidget.TYPE);
+        hostEl.appendChild(root);
+        return new ActiveOrdersWidget(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 first two buttons are the ones that could not come across
+    // unchanged from the terminal's Razor template: they were inline
+    // `onclick="terminalApp.cancelAll()"` / `refreshOrders()`, references to a
+    // global this control must not have. They carry `.panel-cancel-all-btn` and
+    // `.panel-refresh-btn` now — the latter the name the other blotters' rails
+    // already give the identical button — and are wired to deps. Cancel-all
+    // keeps a distinct accessible name from its tooltip, which is why it states
+    // `aria-label` rather than taking the tooltip for both.
+    static _buildRoot(host: TradingHost): HTMLElement {
+        return makePanelRoot('active-orders-panel', host.t('ActiveOrders'), [
+            makeElement('div', 'panel-header', {}, [
+                makeElement('span', '', {}, [host.t('OpenOrders')]),
+                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 active-orders-table', { role: 'table', 'aria-label': host.t('ActiveOrdersList') }, [
+                        makeElement('thead', '', {}, []),
+                        makeElement('tbody', 'active-orders-body', {}, []),
+                    ]),
+                ]),
+                makeElement('div', 'panel-rail', { role: 'toolbar', 'aria-label': host.t('ActiveOrdersActions') }, [
+                    makeIconButton('bt-icon-btn bt-icon-cancel-all panel-cancel-all-btn', host.t('CancelAll'), 'bi-x-circle',
+                        { 'aria-label': host.t('CancelAllOrders') }),
+                    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: ActiveOrdersDeps) {
+        this._host = assertHost(deps?.host, 'ActiveOrdersWidget');
+        for (const name of ['cancelOrder', 'dismissOrder', 'editOrderField', 'replaceOrder', 'cancelAllOrders', 'refreshOrders'] as const) {
+            if (typeof deps?.[name] !== 'function')
+                throw new Error(`ActiveOrdersWidget: dep "${name}" is required`);
+        }
+
+        this.rootEl = rootEl;
+        this._deps = deps;
+        this.el = this.rootEl.querySelector('.active-orders-body');
+        this._closeBtn = this.rootEl.querySelector('.panel-close-btn');
+        this._cancelAllBtn = this.rootEl.querySelector('.panel-cancel-all-btn');
+        this._refreshBtn = this.rootEl.querySelector('.panel-refresh-btn');
+        this._exportBtn = this.rootEl.querySelector('.panel-export-btn');
+        this._orders = [];
+
+        this._closeBtn?.addEventListener('click', (e) => {
+            e.preventDefault();
+            this._host.close();
+        });
+
+        this._cancelAllBtn?.addEventListener('click', (e) => {
+            e.preventDefault();
+            this._deps.cancelAllOrders();
+        });
+
+        this._refreshBtn?.addEventListener('click', (e) => {
+            e.preventDefault();
+            this._deps.refreshOrders();
+        });
+
+        this._exportBtn?.addEventListener('click', (e) => {
+            e.preventDefault();
+            this._export();
+        });
+
+        const head = this.rootEl.querySelector('.active-orders-table thead');
+        this._grid = head && this.el
+            ? new DataGrid<OrderRow>({
+                head: head as HTMLElement,
+                body: this.el,
+                columns: this._columns(),
+                // Newest order on top by default (localId is monotonic) — the resting view puts the
+                // user's most recent actions where they look, instead of raw cache order. Natural
+                // array order is "newest first" too (deltas unshift), but only by accident; any
+                // header click re-renders the same array through the sorter.
+                defaultSort: { col: 'id', dir: 'desc' },
+                // The register tx, not the friendly localId shown in the ID column: it is what
+                // cancel / replace / inline edit address an order by.
+                rowKey: (o) => String(o.id),
+                emptyText: this._host.t('NoActiveOrders'),
+                // Terminal rows are greyed out so the live ones stay visually prominent.
+                rowClass: (o) => ActiveOrdersWidget._rowClass(o),
+            })
+            : null;
+
+        this._host.register(this);
+    }
+
+    dispose(): void {
+        this._host.unregister(this);
+        try { this.rootEl.remove(); } catch { /* already detached */ }
+    }
+
+    update(orders: OrderRow[]): void {
+        this._orders = orders || [];
+        this._grid?.setRows(this._orders);
+    }
+
+    // Export the table to .xlsx in the currently rendered (sorted) order, with the
+    // same localized side/type/status texts the user sees on screen — the columns
+    // carry both forms, so the sheet cannot drift from the table.
+    _export(): void {
+        this._grid?.download('orders', this._host.t('OpenOrders'));
+    }
+
+    /// Apply a single order delta from the feed. Insert if new, merge if known.
+    /// Nothing drops out of the list: Filled and Cancelled rows stay so the user
+    /// can watch an order's transitions instead of having a row vanish, and a
+    /// Rejected row stays so its reason can be read on hover and dismissed
+    /// explicitly through the × button.
+    applyDelta(order: OrderRow): void {
+        if (!order || order.id == null) return;
+        const idx = this._orders.findIndex(o => o.id === order.id);
+        if (idx >= 0)
+            this._orders[idx] = { ...this._orders[idx], ...order };
+        else
+            this._orders.unshift(order);
+        this.update(this._orders);
+    }
+
+    /// Remove a row from the local view without touching the server. Used by the
+    /// × button on a terminal order (nothing left to cancel), and in any other
+    /// client-side dismiss path.
+    removeOrder(orderId: number): void {
+        const idx = this._orders.findIndex(o => o.id === orderId);
+        if (idx >= 0) {
+            this._orders.splice(idx, 1);
+            this.update(this._orders);
+        }
+    }
+
+    getOrder(orderId: number): OrderRow | undefined {
+        return this._orders.find(o => o.id === orderId);
+    }
+
+    startInlineEdit(orderId: number, field: 'quantity' | 'limitPrice' | 'stopPrice'): void {
+        const order = this.getOrder(orderId);
+        if (!order) return;
+        // Addressed by the grid's row key (the register tx) and the column key, so
+        // the edit lands on the right cell whatever the sort is. A lookup that
+        // scanned the rendered ID column for the order id would never match, because
+        // that column shows the friendly counter.
+        const cell = this._grid?.cellElement(String(orderId), field);
+        if (!cell || cell.querySelector('input')) return;
+        const currentValue = order[field];
+        const input = document.createElement('input');
+        input.type = 'number';
+        input.className = 'inline-edit-input';
+        input.value = String(currentValue ?? '');
+        input.step = field === 'quantity' ? '1' : '0.01';
+        input.min = field === 'quantity' ? '1' : '0.01';
+        cell.textContent = '';
+        cell.appendChild(input);
+        input.focus();
+        input.select();
+        const commit = () => {
+            const newVal = parseFloat(input.value);
+            if (isNaN(newVal) || newVal <= 0) { this.update(this._orders); return; }
+            if (newVal === currentValue) { this.update(this._orders); return; }
+            const updated = { quantity: order.quantity, limitPrice: order.limitPrice, stopPrice: order.stopPrice };
+            updated[field] = newVal;
+            this._deps.replaceOrder(orderId, updated.quantity!, updated.limitPrice!, updated.stopPrice!);
+        };
+        input.addEventListener('blur', commit);
+        input.addEventListener('keydown', (e) => {
+            if (e.key === 'Enter') { e.preventDefault(); input.blur(); }
+            if (e.key === 'Escape') { this.update(this._orders); }
+        });
+    }
+
+    // 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.
+    _columns(): GridColumn<OrderRow>[] {
+        // `label`, not `t` — every row lambda below binds `o` for the order,
+        // but keeping the translator under a name of its own reads clearer
+        // next to the presentation object it sits beside.
+        const label = (key: string) => this._host.t(key);
+        const presentation = this._host.presentation;
+        return [
+            {
+                key: 'id',
+                header: label('ID'),
+                exportable: true,
+                // Per-user friendly counter (1, 2, 3, …) issued by the host. `o.id`
+                // keeps the register tx for cancel / replace routing; `o.localId` is
+                // just the badge the user wants to see. Rows cached from before the
+                // counter shipped have no localId — fall back to id so they don't go
+                // blank until the next snapshot replay reassigns one.
+                value: (o) => o.localId ?? o.id,
+            },
+            {
+                key: 'instrument',
+                header: label('Sym'),
+                exportable: true,
+                value: (o) => o.instrument,
+            },
+            {
+                key: 'side',
+                header: label('Side'),
+                exportable: true,
+                value: (o) => o.side,
+                render: (o) => presentation.sideText(o.side!),
+                cellClass: (o) => presentation.sideClass(o.side!),
+                exportValue: (o) => presentation.sideText(o.side!),
+            },
+            {
+                key: 'type',
+                header: label('Type'),
+                exportable: true,
+                value: (o) => o.type,
+                render: (o) => presentation.typeText(o.type!, o.limitPrice!, o.stopPrice!),
+                exportValue: (o) => presentation.typeText(o.type!, o.limitPrice!, o.stopPrice!),
+            },
+            {
+                key: 'quantity',
+                header: label('Qty'),
+                exportable: true,
+                value: (o) => o.quantity,
+                render: (o) => formatQty(o.quantity),
+                cellClass: (o) => ActiveOrdersWidget._editableClass(o, 'quantity'),
+                bindCell: (td, o) => this._bindInlineEdit(td, o, 'quantity'),
+            },
+            {
+                key: 'limitPrice',
+                header: label('Price'),
+                exportable: true,
+                value: (o) => o.limitPrice,
+                render: (o) => o.limitPrice ? formatPrice(o.limitPrice) : label('MKT'),
+                cellClass: (o) => ActiveOrdersWidget._editableClass(o, 'limitPrice'),
+                bindCell: (td, o) => this._bindInlineEdit(td, o, 'limitPrice'),
+                exportValue: (o) => o.limitPrice ?? label('MKT'),
+            },
+            {
+                key: 'stopPrice',
+                header: label('Stop'),
+                exportable: true,
+                value: (o) => o.stopPrice,
+                render: (o) => o.stopPrice ? formatPrice(o.stopPrice) : '--',
+                cellClass: (o) => ActiveOrdersWidget._editableClass(o, 'stopPrice'),
+                bindCell: (td, o) => this._bindInlineEdit(td, o, 'stopPrice'),
+                exportValue: (o) => o.stopPrice ?? '',
+            },
+            {
+                key: 'status',
+                header: label('Status'),
+                exportable: true,
+                value: (o) => o.status,
+                render: (o) => this._statusCell(o),
+                exportValue: (o) => presentation.statusText(o.status!),
+            },
+            {
+                key: 'actions',
+                header: label('Actions'),
+                headerHidden: true,
+                exportable: false,
+                cellClass: () => 'position-actions',
+                render: (o) => this._actionButton(o),
+            },
+        ];
+    }
+
+    static _rowClass(order: OrderRow): string {
+        if (order.status === OrderStates.Filled) return 'order-filled';
+        if (order.status === OrderStates.Rejected) return 'order-rejected';
+        if (order.status === OrderStates.Cancelled) return 'order-cancelled';
+        return '';
+    }
+
+    // An order can still be modified while the venue holds it. A market order has
+    // no limit price and an unconditional order no stop price, so those cells have
+    // nothing to edit even then.
+    static _canEdit(order: OrderRow, field: 'quantity' | 'limitPrice' | 'stopPrice'): boolean {
+        const modifiable = order.status === OrderStates.Active || order.status === OrderStates.Sent;
+        return modifiable && (field === 'quantity' || !!order[field]);
+    }
+
+    static _editableClass(order: OrderRow, field: 'quantity' | 'limitPrice' | 'stopPrice'): string {
+        return ActiveOrdersWidget._canEdit(order, field) ? 'cell-editable' : '';
+    }
+
+    // Double-click to edit belongs to the whole cell rather than to a control
+    // inside it, which is why it is wired here instead of returned by render().
+    _bindInlineEdit(td: HTMLTableCellElement, order: OrderRow, field: 'quantity' | 'limitPrice' | 'stopPrice'): void {
+        if (!ActiveOrdersWidget._canEdit(order, field)) return;
+        td.addEventListener('dblclick', () => this._deps.editOrderField(order.id!, field));
+    }
+
+    // Status text, plus a hoverable icon carrying the rejection reason. Some
+    // venues wrap the human-readable rejection inside a JSON blob;
+    // cleanRejectReason extracts `.message` and falls back to the raw string.
+    // The reason goes on the element's title property, so no quote escaping is
+    // involved the way it was when this row was built as markup.
+    _statusCell(order: OrderRow): string | Node {
+        const text = this._host.presentation.statusText(order.status!);
+        const reason = order.status === OrderStates.Rejected ? cleanRejectReason(order.rejectReason) : '';
+        if (!reason) return text;
+
+        const cell = document.createDocumentFragment();
+        cell.appendChild(document.createTextNode(text + ' '));
+        const icon = document.createElement('i');
+        icon.className = 'bi bi-question-circle reject-reason-icon';
+        icon.title = reason;
+        cell.appendChild(icon);
+        return cell;
+    }
+
+    // The × button, wired to the controller through deps. Status decides what it
+    // means: Pending / Active is a real cancel over the wire, while Filled /
+    // Rejected / Cancelled have nothing left to cancel — the row is history kept
+    // around so the user can read its final state, so the button dismisses it
+    // locally.
+    _actionButton(order: OrderRow): Node {
+        const isTerminal = order.status === OrderStates.Filled
+            || order.status === OrderStates.Rejected
+            || order.status === OrderStates.Cancelled;
+        const title = isTerminal ? this._host.t('Dismiss') : this._host.t('Cancel order');
+
+        const button = document.createElement('button');
+        button.type = 'button';
+        button.className = 'bt-icon-btn bt-icon-cancel';
+        button.title = title;
+        button.setAttribute('aria-label', `${title} #${order.id}`);
+        const icon = document.createElement('i');
+        icon.className = 'bi bi-x-circle';
+        button.appendChild(icon);
+        button.addEventListener('click', () => {
+            if (isTerminal) this._deps.dismissOrder(order.id!);
+            else this._deps.cancelOrder(order.id!);
+        });
+        return button;
+    }
+}

package/src/control-types.ts

@@ -0,0 +1,24 @@
+// The identifiers a host and a control agree on for each kind of control this
+// package ships.
+//
+// These strings used to be spelled out independently in four places — a docking
+// manager's panel table, its default layouts, each control's static TYPE
+// literal and a Razor panels menu — so a typo in any one of them produced a
+// panel that opened but never received data, with nothing to compare against.
+//
+// The VALUES are load-bearing and must not be edited. A host writes them into
+// whatever it persists its layout as, so renaming one orphans every saved
+// layout that mentions it.
+//
+// Only the kinds this package implements are named here. A host that has more
+// control kinds of its own declares those itself and merges the two sets; that
+// keeps every identifier declared exactly once, by whoever owns the control it
+// names.
+export const ControlTypes = {
+    Watchlist: 'watchlist',
+    ActiveOrders: 'activeOrders',
+    TradeHistory: 'tradeHistory',
+    Positions: 'positions',
+} as const;
+
+export type ControlType = typeof ControlTypes[keyof typeof ControlTypes];

package/src/dom.ts

@@ -0,0 +1,68 @@
+// Element construction for controls that build their own DOM.
+//
+// A control that clones a <template> out of the page it happens to live on
+// cannot render anywhere else, so the markup has to move into the control. It
+// then has to stay readable as markup, which four lines of createElement /
+// className / setAttribute / appendChild per element does not.
+//
+// Nothing here has an import, touches a global or knows what a trading control
+// is — it is a spelling of `document.createElement`, and the shape of the call
+// mirrors the shape of the tag it replaces:
+//
+//   <div class="panel-header"><span>Positions</span></div>
+//   makeElement('div', 'panel-header', {}, [makeElement('span', '', {}, ['Positions'])])
+
+/// One element. `className` may be empty and `attrs` may be empty — both are
+/// then left off entirely, so the result matches markup that never carried
+/// them. Children are appended in order; a string child becomes a text node.
+export function makeElement(
+    tag: string,
+    className: string,
+    attrs: Record<string, string>,
+    children: Array<Node | string>,
+): HTMLElement {
+    const element = document.createElement(tag);
+    if (className) element.className = className;
+    for (const [name, value] of Object.entries(attrs)) element.setAttribute(name, value);
+    for (const child of children)
+        element.appendChild(typeof child === 'string' ? document.createTextNode(child) : child);
+    return element;
+}
+
+/// A Bootstrap icon glyph — `<i class="bi bi-x"></i>`. Every icon in a control's
+/// panel chrome is one of these, always with the `bi` base class.
+export function makeIcon(iconClass: string): HTMLElement {
+    return makeElement('i', `bi ${iconClass}`, {}, []);
+}
+
+/// An icon button from the panel chrome: one glyph, and the same text as both
+/// tooltip and accessible name. `className` carries the full class list
+/// because the buttons differ by more than one modifier
+/// (`bt-icon-btn bt-icon-cancel panel-close-btn`).
+export function makeIconButton(
+    className: string,
+    label: string,
+    iconClass: string,
+    attrs: Record<string, string>,
+): HTMLButtonElement {
+    return makeElement('button', className, { title: label, 'aria-label': label, ...attrs },
+        [makeIcon(iconClass)]) as HTMLButtonElement;
+}
+
+/// The panel root every control builds: `.terminal-panel` plus the control's own
+/// modifier class, carrying the region role and its accessible name.
+///
+/// The structure is a contract in two directions and both are load-bearing. A
+/// host stylesheet targets these class names, and a docking host may lift
+/// `.panel-header`'s children into its own tab strip, which needs
+/// `.terminal-panel` to be the root's only element child.
+export function makePanelRoot(modifierClass: string, label: string, children: Array<Node | string>): HTMLElement {
+    return makeElement('div', `terminal-panel ${modifierClass}`, { role: 'region', 'aria-label': label }, children);
+}
+
+/// A unique element id for one control instance. Time plus a random tail: the
+/// time alone collides when a host restores a saved layout, which creates every
+/// panel inside one millisecond.
+export function makePanelId(type: string): string {
+    return `panel-${type}-${Date.now().toString(36)}-${Math.floor(Math.random() * 1000).toString(36)}`;
+}

package/src/formatters.ts

@@ -0,0 +1,72 @@
+// Value formatters — pure functions over numbers, prices, quantities, times
+// and one venue string.
+//
+// Nothing here reaches a translator, the DOM, a singleton or a window global,
+// and the module has no import and no side effect. That is why it is its own
+// file: this is the half of the presentation a control needs in ANY host. The
+// other half — a host's own vocabulary for a side, a type, a status — is
+// `TradingPresentation`, which is handed to a control rather than imported by
+// it.
+type Numeric = number | string | null | undefined;
+
+/// Digits chosen from the magnitude of the price. A fixed two decimals
+/// collapses distinct ticks of a penny instrument onto the same "0.44" —
+/// on the Y axis, in the order book, in the price header, everywhere — while
+/// six decimals on a $76,000 print is noise.
+export function formatPrice(price: Numeric): string {
+    if (price == null || isNaN(Number(price))) return '--';
+    const n = Number(price);
+    const a = Math.abs(n);
+    let prec = 2;
+    if (a < 1) prec = 4;
+    if (a < 0.1) prec = 5;
+    if (a < 0.001) prec = 6;
+    if (a >= 1000) prec = 1;
+    if (a >= 10000) prec = 0;
+    return n.toFixed(prec);
+}
+
+/// Crypto quantities carry up to 8 decimals, so the cap is 8 rather than the
+/// locale default of 3; trailing zeros are trimmed because a size of "1" reads
+/// better than "1.00000000" in a ladder.
+export function formatQty(qty: Numeric): string {
+    if (qty == null) return '--';
+    const n = Number(qty);
+    if (!isFinite(n)) return '--';
+    return n.toLocaleString(undefined, { maximumFractionDigits: 8 });
+}
+
+/// Wall-clock time of day, 24h, seconds included — a trade blotter is read by
+/// eye against the tape, so the format is fixed rather than locale-driven.
+export function formatTime(dateStr: string | number | Date | null | undefined): string {
+    const d = new Date(dateStr as string);
+    return d.toLocaleTimeString('en-US', { hour12: false, hour: '2-digit', minute: '2-digit', second: '2-digit' });
+}
+
+/// A signed figure: profit carries an explicit `+` so a gain and a loss are
+/// told apart by the number alone, without relying on the colour class.
+export function formatPnl(pnl: Numeric): string {
+    if (pnl == null) return '--';
+    const val = Number(pnl);
+    const sign = val >= 0 ? '+' : '';
+    return sign + val.toFixed(2);
+}
+
+/// Some venue adapters hand us a wrapped error string like
+///   "failed to complete request (err=Forbidden): {"code":40310000,"message":"cost basis must be >= ..."}"
+/// The raw form is stored for audit, but users should see the human-readable
+/// message only. Pull `message` out of the embedded JSON when present;
+/// otherwise return the reason as-is.
+export function cleanRejectReason(reason: string | null | undefined): string {
+    if (!reason) return '';
+    const i = reason.indexOf('{');
+    const j = reason.lastIndexOf('}');
+    if (i >= 0 && j > i) {
+        try {
+            const parsed = JSON.parse(reason.substring(i, j + 1));
+            if (parsed && typeof parsed.message === 'string' && parsed.message.length > 0)
+                return parsed.message;
+        } catch { /* fall through to raw */ }
+    }
+    return reason;
+}

package/src/index.ts

@@ -0,0 +1,52 @@
+export { MarketDataLevels, PRESENTATION_CLASSES, assertHost } from './trading-host.js';
+
+export type {
+    HostStore,
+    MarketDataClient,
+    MarketDataLevel,
+    TickerSink,
+    TradingApi,
+    TradingContext,
+    TradingControl,
+    TradingHost,
+    TradingPresentation,
+} from './trading-host.js';
+
+export type {
+    BalanceRow,
+    InstrumentRow,
+    OrderRow,
+    OrderSide,
+    OrderStatus,
+    OrderType,
+    PositionRow,
+    QuoteStats,
+    TradeRow,
+} from './trading-data.js';
+
+export { ControlTypes } from './control-types.js';
+
+export type { ControlType } from './control-types.js';
+
+export { cleanRejectReason, formatPnl, formatPrice, formatQty, formatTime } from './formatters.js';
+
+// A host that renders its own chrome around these controls builds it with the
+// same helpers, so the panel it wraps and the panel it wraps them in agree on
+// class names.
+export { makeElement, makeIcon, makeIconButton, makePanelId, makePanelRoot } from './dom.js';
+
+export { ActiveOrdersWidget, OrderStates } from './active-orders-widget.js';
+
+export type { ActiveOrdersDeps } from './active-orders-widget.js';
+
+export { PositionsWidget } from './positions-widget.js';
+
+export type { PositionsDeps } from './positions-widget.js';
+
+export { TradeHistoryWidget } from './trade-history-widget.js';
+
+export type { TradeHistoryDeps } from './trade-history-widget.js';
+
+export { WatchlistWidget } from './watchlist-widget.js';
+
+export type { WatchlistDeps } from './watchlist-widget.js';