@dxfeed/dxlink-console-core 0.0.0-stage → 0.10.0

package/build/index.d.mts

@@ -0,0 +1,524 @@
+import * as react from 'react';
+import { ReactNode, ComponentType, Provider, Context, Component, ErrorInfo } from 'react';
+import { Theme, ThemeOptions } from '@mui/material/styles';
+import { DXLinkError, DXLinkConnectionState, DXLinkAuthState, DXLinkConnectionDetails, DXLinkClient, DXLinkChannel } from '@dxfeed/dxlink-api';
+import * as zustand from 'zustand';
+import { StoreApi } from 'zustand';
+
+/**
+ * One channel service, as the channels area sees it.
+ *
+ * The area knows nothing about FEED, DOM, INDICHART or RPC: it renders an add-button per
+ * registered plugin, holds one request value per plugin, and asks the plugin to turn that
+ * request into a channel config and then to render the channel. Everything that used to be
+ * a four-way switch is a lookup on this descriptor.
+ *
+ * Plugins reach the connection the same way the channel components always have —
+ * `useConnectionVM()` for the view model, `useVM` to read its state. Those two are the
+ * whole host API; there is no plugin-specific context.
+ */
+interface ChannelPlugin<Config, Request> {
+    /**
+     * Stable identifier for this service, unique among the registered plugins.
+     *
+     * Any string: core deliberately holds no list of known kinds, so a host can register a
+     * service this package has never heard of. Whoever reads a configured kind name is the one
+     * who validates it, against the plugins actually registered.
+     */
+    kind: string;
+    /** Add-button label; also the channel title and the error-boundary name. */
+    label: string;
+    icon: ReactNode;
+    dialogTitle: string;
+    /** Widened for forms that need the room — the RPC form carries three panes. */
+    dialogMaxWidth?: 'sm' | 'md';
+    /**
+     * The value the request form starts from.
+     *
+     * Called once per plugin when the area mounts, never again: request values are kept
+     * between dialog opens so several similar channels are quick to create.
+     */
+    createRequest: () => Request;
+    RequestForm: ComponentType<{
+        value: Request;
+        onChange: (next: Request) => void;
+    }>;
+    /** Whether "Open channel" is enabled. Omitted means always. */
+    canOpen?: (request: Request) => boolean;
+    /**
+     * The config to open a channel with, or null when this request cannot produce one.
+     *
+     * Only RPC can fail here: its service, method and message are resolved out of a
+     * descriptor set, and a stale selection must not open a broken channel.
+     */
+    buildConfig: (request: Request) => Config | null;
+    Channel: ComponentType<{
+        title: string;
+        config: Config;
+    }>;
+}
+/**
+ * A plugin with its `Request` and `Config` types erased, as the registry stores them.
+ *
+ * The erasure is sound because of one invariant the area upholds: a plugin is only ever
+ * handed values that came from that same plugin. A request starts at its own
+ * `createRequest()` and is only ever replaced by its own `RequestForm`; a config comes from
+ * its own `buildConfig()` and goes to its own `Channel`. Neither type crosses a plugin
+ * boundary, so the area can treat both as `unknown` without ever being wrong.
+ *
+ * The cost is that the area cannot type-check the pairing — that is what
+ * {@link defineChannelPlugin} is for, and it is the trade a registry makes in exchange for
+ * not naming its plugins.
+ */
+type ErasedChannelPlugin = ChannelPlugin<unknown, unknown>;
+/**
+ * Declare a channel plugin.
+ *
+ * Type-checks the descriptor against its own `Config` and `Request` — the form, the
+ * builder and the channel component all have to agree — and then erases them for the
+ * registry. This is the only place the erasure happens.
+ */
+declare const defineChannelPlugin: <Config, Request>(plugin: ChannelPlugin<Config, Request>) => ErasedChannelPlugin;
+
+/** Connection keepalive timings, in seconds. */
+interface KeepaliveConfig {
+    interval: number;
+    timeout: number;
+    acceptTimeout: number;
+}
+/** A group of fields a host can pin, addressed as one. */
+type ConsoleConfigLock = 'wsUrl' | 'keepalive';
+/** Whether a value names a field group this console knows how to pin. */
+declare const isConsoleConfigLock: (value: unknown) => value is ConsoleConfigLock;
+/**
+ * What a host can decide about a console before anyone opens it.
+ *
+ * These are the values forms **start** with, not the values they hold: everything here
+ * seeds local draft state once and is never written back, so the user stays free to edit.
+ * The exception is {@link ConsoleConfig.locked}, which is how a host says a field is fixed
+ * rather than merely suggested.
+ *
+ * Deliberately small. Anything a single channel service needs — the RPC descriptor-set URL,
+ * say — is that plugin's option rather than a field here, so core does not grow a vocabulary
+ * for services it knows nothing about.
+ */
+interface ConsoleConfig {
+    /** Seeds the connection form's WebSocket URL. Empty means the user supplies one. */
+    wsUrl: string;
+    keepalive: KeepaliveConfig;
+    /**
+     * Which channel kinds the add-channel row offers.
+     *
+     * A set rather than a sequence: button order follows the registered plugins — the list
+     * `ChannelsArea` filters — so ordering this list has no effect on the buttons.
+     *
+     * `null` means every registered plugin, which is the default — with an open kind
+     * vocabulary there is no fixed list to enumerate, so "unrestricted" has to be its own
+     * value rather than a list that happens to name everything. An empty array means none.
+     */
+    channelKinds: readonly string[] | null;
+    /**
+     * Fields the host has pinned. They render read-only rather than hidden — this is a debug
+     * console, so which endpoint you are talking to is worth seeing even when you cannot
+     * change it.
+     */
+    locked: readonly ConsoleConfigLock[];
+}
+/** A partial profile, as each configuration source produces it. */
+interface ConsoleConfigInput {
+    wsUrl?: string;
+    keepalive?: Partial<KeepaliveConfig>;
+    channelKinds?: readonly string[] | null;
+    locked?: readonly ConsoleConfigLock[];
+}
+/**
+ * The profile a console falls back to when nothing is supplied.
+ *
+ * There is no WebSocket URL here, and that is the point: deriving one means knowing how this
+ * console is deployed — whether it sits next to its endpoint, whether a development build
+ * should reach for a shared relay — and core has no business knowing either. A host supplies
+ * it as a source (see {@link resolveConsoleConfig}); until one does, the field starts empty
+ * and the user types it.
+ */
+declare const builtinConsoleConfig: () => ConsoleConfig;
+interface ConsoleConfigSources {
+    /**
+     * Defaults the serving application itself carries — the one place a build-time choice
+     * (say, a development relay) belongs, so nothing below has to know about bundlers.
+     */
+    app?: ConsoleConfigInput;
+    /** What the host injected into the page. The only source allowed to lock a field. */
+    injected?: ConsoleConfigInput;
+    /** What the page URL carried, already parsed. */
+    search?: ConsoleConfigInput;
+}
+/**
+ * Resolve one profile from every source, later sources winning:
+ *
+ * ```
+ * built-in defaults  ←  app defaults  ←  injected config  ←  query string
+ * ```
+ *
+ * Two rules make locking mean something:
+ *  - **only the injected config can lock a field.** A query parameter is written by
+ *    whoever opened the link, so letting it pin a field would be pointless and letting it
+ *    unpin one would make locking a lie.
+ *  - **a locked field ignores its query parameter**, otherwise the pin would not hold.
+ *
+ * Locks deliberately do not gate the app layer: that is the same deployment speaking.
+ *
+ * Every source arrives already parsed. Reading an injected global or a query string is a
+ * standalone-deployment concern and belongs to whoever owns the page; what lives here is the
+ * merge order and the lock rules, which are the same wherever the values came from.
+ */
+declare const resolveConsoleConfig: (sources: ConsoleConfigSources) => ConsoleConfig;
+
+interface ConsolePageProps {
+    /**
+     * Initial values for the console's forms; see {@link ConsoleConfig}.
+     *
+     * Required, like {@link ConsolePageProps.channels}: a profile is a decision about how this
+     * console is deployed, and core reads no globals to guess one. `builtinConsoleConfig()` is
+     * the do-nothing answer if a host genuinely has no preferences.
+     */
+    config: ConsoleConfig;
+    /**
+     * The channel services this console offers.
+     *
+     * Required: which services exist is a composition decision, and a host that leaves the
+     * market-data plugins out never imports their code.
+     */
+    channels: readonly ErasedChannelPlugin[];
+    /**
+     * The theme the console renders with, from `createConsoleTheme()`.
+     *
+     * Optional, and it is the one prop with two right answers. A host that already has a MUI
+     * `ThemeProvider` above this page — the standalone app does — leaves it out, so there is
+     * one theme in the tree rather than a second nested inside the first. A host embedding the
+     * console in a page that is not MUI's passes one, and the console is then self-contained.
+     *
+     * Left out with no provider above, MUI falls back to its own default theme: the console
+     * still works, but looks like stock MUI rather than the console.
+     *
+     * Passing one also hands the host sole ownership of light/dark — see the note on the
+     * component below.
+     */
+    theme?: Theme;
+}
+declare const ConsolePage: ({ config, channels, theme }: ConsolePageProps) => react.JSX.Element;
+
+/**
+ * Build the console theme, optionally layered with a host's own options.
+ *
+ * Overrides are deep-merged on top, later arguments winning — so a host adds a font or
+ * retints the palette without restating the rest. Pass the result to
+ * {@link ConsolePageProps.theme}, or to a `ThemeProvider` above the page.
+ *
+ * **The merge happens on the options, not on the theme**, and it has to. `createTheme`'s own
+ * variadic form (`createTheme(options, ...args)`) merges its extra arguments into the theme it
+ * has already computed, which silently strips anything derived: a `typography.fontFamily`
+ * supplied that way lands on the theme, but `body1`, `h1` and the rest were built from the
+ * default stack a step earlier and keep it. That surfaced as a console rendering in Roboto
+ * while `body` rendered in Inter. Palette entries derive the same way.
+ */
+declare const createConsoleTheme: (...overrides: readonly ThemeOptions[]) => Theme;
+
+interface ChannelsAreaProps {
+    /**
+     * The channel services this console offers, in the order their add-buttons appear.
+     *
+     * Required, and deliberately so: which services exist is a composition decision, not a
+     * default. A console that should not offer market data simply does not register those
+     * plugins — and then never imports their code either.
+     */
+    channels: readonly ErasedChannelPlugin[];
+}
+/**
+ * Channels area (draft / presentational only). Owns the open channels and the
+ * per-service channel-request dialog. Request forms keep their values between
+ * opens so the user can quickly open several channels; each opened channel
+ * manages its own state.
+ *
+ * Knows nothing about any particular service. Add-buttons, dialog titles, request forms,
+ * validation and the channel bodies all come from the registered {@link ChannelPlugin}s, so
+ * adding or removing a service touches only the composition site.
+ *
+ * Two filters, doing different jobs: the registered plugins say which services exist in
+ * this build, and the profile's `channelKinds` says which of those this deployment offers
+ * (`null` — the default — meaning all of them). The second filters buttons only — an
+ * already-open channel keeps rendering, so a profile that disagrees with what is on screen
+ * degrades instead of crashing.
+ */
+declare const ChannelsArea: ({ channels }: ChannelsAreaProps) => react.JSX.Element;
+
+/**
+ * One open channel.
+ *
+ * `config` is opaque. It was produced by the plugin named by `kind` and is only ever handed
+ * back to that same plugin, so the channels area never needs to know what is in it — which
+ * is what keeps the four services' types (and their dependencies) out of this feature.
+ */
+interface DraftChannel {
+    id: string;
+    kind: string;
+    config: unknown;
+}
+
+/**
+ * A protocol error captured for display, stamped with the time it arrived.
+ *
+ * Used by both scopes: connection errors aggregate on the `ConnectionViewModel`,
+ * channel errors stay on the channel VM that owns them.
+ */
+interface TimestampedError {
+    /** Stable identity for React keys — errors are prepended, so an index is not stable. */
+    id: number;
+    type: string;
+    message: string;
+    time: string;
+}
+/**
+ * How many errors one scope retains.
+ *
+ * A server that rejects every subscription in a large batch can produce thousands, and a
+ * debug console is left open for a long time. Only the most recent are useful, and an
+ * unbounded list would grow memory for the session and render one alert per entry.
+ */
+declare const MAX_ERRORS = 200;
+/** Prepend an error to a list, newest first, capped at {@link MAX_ERRORS}. */
+declare const prependError: (errors: readonly TimestampedError[], error: DXLinkError) => TimestampedError[];
+
+interface ChannelWidgetProps {
+    icon: React.ReactNode;
+    title: string;
+    subtitle?: string;
+    /** Status slot (e.g. a Chip) shown before the collapse/close actions. */
+    status?: React.ReactNode;
+    /**
+     * Protocol channel id, shown next to the subtitle so a card can be correlated with
+     * a protocol log. Distinct from the card's own sequential number in `title`.
+     */
+    channelId?: number | null;
+    /** Parameters the channel was opened with, listed as chips under the header. */
+    parameters?: Readonly<Record<string, unknown>> | null;
+    /**
+     * Errors scoped to this channel. Surfaced here rather than in the connection-level
+     * error center, so it stays obvious which channel failed.
+     */
+    errors?: readonly TimestampedError[];
+    onClearErrors?: () => void;
+    /**
+     * Fired once when the user closes the channel. The card stays (closed state is
+     * owned here) — use this to release the channel's resources (e.g. close the
+     * underlying dxlink channel).
+     */
+    onClose?: () => void;
+    defaultExpanded?: boolean;
+    children: React.ReactNode;
+}
+/**
+ * Generic collapsible channel card shell (draft / presentational). Every channel
+ * kind (feed, dom, indichart) renders its content inside this shell.
+ *
+ * Closing is a channel-view concern: it does NOT remove the card from the area —
+ * the widget owns its own closed state. Closing is terminal (the dxlink channel
+ * CLOSED state): the card stays as a header-only record marked "closed" — its
+ * content is no longer rendered — and it cannot be reopened.
+ */
+declare const ChannelWidget: ({ icon, title, subtitle, status, channelId, parameters, errors, onClearErrors, onClose, defaultExpanded, children, }: ChannelWidgetProps) => react.JSX.Element;
+
+/**
+ * Base contract for every ViewModel. A ViewModel owns its UI state in a vanilla
+ * Zustand store and exposes `dispose()` to release resources (listeners, sockets).
+ *
+ * `dispose()` MUST be idempotent: React 19 StrictMode mounts → unmounts → remounts
+ * components, so a VM may be disposed and re-created; double-dispose must be a no-op.
+ */
+interface ViewModel<State = unknown> {
+    readonly store: StoreApi<State>;
+    dispose(): void;
+}
+/**
+ * Bind a React component to a slice of a ViewModel's store. Re-renders only when
+ * the selected slice changes. This is the single binding primitive for the app —
+ * no manual `useEffect` listener plumbing in views.
+ */
+declare const useVM: <State, Slice>(vm: {
+    readonly store: StoreApi<State>;
+}, selector: (state: State) => Slice) => Slice;
+/**
+ * Own a ViewModel for the lifetime of the calling component.
+ *
+ * StrictMode-safe: the VM is constructed exactly once via lazy `useState` init
+ * (never `new VM()` inline in render), and `dispose()` runs on unmount. Combined
+ * with an idempotent `dispose()`, this prevents leaking resources across React's
+ * mount → unmount → remount double-invoke in development.
+ */
+declare const useOwnedViewModel: <VM extends {
+    dispose(): void;
+}>(factory: () => VM) => VM;
+/**
+ * Create a typed React context for sharing a ViewModel down a page subtree
+ * (avoids prop-drilling). The returned `useContextValue` hook throws if used
+ * outside its provider.
+ */
+declare const createViewModelContext: <VM>(displayName: string) => {
+    Provider: Provider<VM | null>;
+    Context: Context<VM | null>;
+    useContextValue: () => VM;
+};
+
+/** Connection parameters entered in the form and passed to the client config. */
+interface ConnectionParams {
+    keepaliveInterval: number;
+    keepaliveTimeout: number;
+    acceptKeepaliveTimeout: number;
+}
+interface ConnectionVMState {
+    connection: DXLinkConnectionState;
+    /**
+     * Tri-state auth gating: `undefined` until we know (not connected / connecting),
+     * then the server-reported `DXLinkAuthState`. Never seeded to UNAUTHORIZED so a
+     * no-auth server doesn't flash a token form.
+     */
+    auth: DXLinkAuthState | undefined;
+    details: DXLinkConnectionDetails | null;
+    errors: TimestampedError[];
+    /**
+     * Identifies the current client instance. Bumped on each fresh {@link connect}
+     * (new client) but NOT on {@link reconnect} (same client). The channels area uses
+     * it as a React remount key, so a brand-new connection starts with no channels
+     * while a reconnect preserves the open ones.
+     */
+    sessionId: number;
+    /**
+     * `true` once the current client has reached AUTHORIZED. Stays `true` through a
+     * reconnect (the same client re-opens its channels itself), so the channels area
+     * survives the connection / auth flicker. Reset on disconnect / fresh connect.
+     */
+    everAuthorized: boolean;
+}
+/**
+ * Page-scoped ViewModel wrapping a single {@link DXLinkWebSocketClient}. Owns the
+ * client as a private field (kept off the store), wires its listeners once, and
+ * maps connection / auth / error events into the store. Commands: connect,
+ * reconnect, disconnect, setAuthToken, clearErrors.
+ *
+ * Debug-console client opts are preserved from the legacy console: `logLevel:
+ * DEBUG` and `maxReconnectAttempts: 1` (a debug console deliberately limits
+ * reconnect).
+ */
+declare class ConnectionViewModel implements ViewModel<ConnectionVMState> {
+    readonly store: zustand.StoreApi<ConnectionVMState>;
+    private client;
+    connect: (url: string, params: ConnectionParams) => void;
+    reconnect: () => void;
+    disconnect: () => void;
+    setAuthToken: (token: string) => void;
+    /**
+     * The live client, for opening channels (e.g. building a FeedViewModel). Non-null
+     * only while connected — channel views are gated behind the AUTHORIZED state.
+     */
+    getClient: () => DXLinkClient | null;
+    clearErrors: () => void;
+    /**
+     * Release the client + listeners. Idempotent and NON-permanent: after a dispose
+     * (e.g. React StrictMode's setup→cleanup→setup, which reuses the same VM via
+     * useState) the VM stays usable — the next `connect()` simply builds a fresh
+     * client. A real page unmount disposes it for good because nothing calls it again.
+     */
+    dispose: () => void;
+    private handleConnectionState;
+    private handleAuthState;
+    private handleError;
+    /** Pull the current state straight off the client (e.g. right after connect()). */
+    private syncFromClient;
+    private teardownClient;
+}
+
+/** Provides the page-scoped {@link ConnectionViewModel} to the console subtree. */
+declare const ConnectionProvider: react.Provider<ConnectionViewModel | null>;
+/** Read the page's {@link ConnectionViewModel} (throws if used outside the provider). */
+declare const useConnectionVM: () => ConnectionViewModel;
+
+interface ErrorBoundaryProps {
+    children: ReactNode;
+    /** Heading for the fallback alert — name the part that failed. */
+    title?: string;
+}
+interface ErrorBoundaryState {
+    error: Error | null;
+}
+/**
+ * Contains a render-time failure to one subtree instead of blanking the app.
+ *
+ * Channel cards are the motivating case: they construct ViewModels (which throw if the
+ * connection vanished between opening the dialog and mounting) and they host a
+ * third-party chart component. Without a boundary either one takes down the whole
+ * console, losing every other open channel too.
+ */
+declare class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+    state: ErrorBoundaryState;
+    static getDerivedStateFromError(error: Error): ErrorBoundaryState;
+    componentDidCatch(error: Error, info: ErrorInfo): void;
+    render(): ReactNode;
+}
+
+/**
+ * The slice of a channel ViewModel's state that describes its channel and what went
+ * wrong on it. Every channel VM's state extends this.
+ *
+ * `channelParameters` is optional: INDICHART's parameters carry the full source of every
+ * indicator, so that VM omits the field rather than retaining a third copy of them.
+ */
+interface ChannelErrorState {
+    /** Protocol channel id, for correlating with a protocol log. Null until opened. */
+    channelId: number | null;
+    /** Errors scoped to THIS channel — connection errors live on the connection VM. */
+    errors: TimestampedError[];
+    /** Parameters this channel was actually opened with. Null until opened. */
+    channelParameters?: Readonly<Record<string, unknown>> | null;
+}
+/** Initial values for the slice, for a VM's store initializer. */
+declare const initialChannelErrorState: () => Required<ChannelErrorState>;
+/**
+ * Tracks one channel's identity and errors on behalf of a ViewModel.
+ *
+ * Every channel VM needs the same three things — register an error listener, record the
+ * channel id and parameters on open, and expose a clear command. Keeping it here means
+ * one place to change, instead of four copies that drift.
+ *
+ * The `Partial<S>` casts are needed because TypeScript cannot prove a literal is a
+ * partial of the generic `S`; the constraint on `S` guarantees the keys exist.
+ */
+declare class ChannelErrorTracker<S extends ChannelErrorState> {
+    private readonly store;
+    constructor(store: StoreApi<S>);
+    /**
+     * Start collecting errors from a freshly opened channel and record its identity.
+     *
+     * `withParameters: false` skips recording the parameters, for services whose
+     * parameters are large and already available elsewhere (INDICHART).
+     */
+    attach: (channel: DXLinkChannel, { withParameters }?: {
+        withParameters?: boolean | undefined;
+    }) => void;
+    /** Stop collecting. Errors already recorded are kept — they are a log. */
+    detach: (channel: DXLinkChannel) => void;
+    clear: () => void;
+    private handleError;
+}
+
+/**
+ * Provides the resolved {@link ConsoleConfig} to the console subtree.
+ *
+ * A context rather than props because the values are read in two places at different
+ * depths — the connection panel and the channels area — and threading a profile through
+ * every layer between would be noise. Same reasoning as the connection ViewModel context;
+ * this one carries plain data, so it is not built on the ViewModel helper.
+ */
+declare const ConsoleConfigProvider: react.Provider<ConsoleConfig | null>;
+/** Read the console's configuration profile (throws if used outside the provider). */
+declare const useConsoleConfig: () => ConsoleConfig;
+
+export { type ChannelErrorState, ChannelErrorTracker, type ChannelPlugin, ChannelWidget, ChannelsArea, type ChannelsAreaProps, ConnectionProvider, ConnectionViewModel, type ConsoleConfig, type ConsoleConfigInput, type ConsoleConfigLock, ConsoleConfigProvider, type ConsoleConfigSources, ConsolePage, type ConsolePageProps, type DraftChannel, type ErasedChannelPlugin, ErrorBoundary, type KeepaliveConfig, MAX_ERRORS, type TimestampedError, type ViewModel, builtinConsoleConfig, createConsoleTheme, createViewModelContext, defineChannelPlugin, initialChannelErrorState, isConsoleConfigLock, prependError, resolveConsoleConfig, useConnectionVM, useConsoleConfig, useOwnedViewModel, useVM };