@columenlabs/lumen-ui 0.0.0-stage → 0.2.0

package/dist/market/live.js

@@ -0,0 +1,444 @@
+/**
+ * Live market data in the browser (design market-live): one hub per tab, one
+ * socket per tab however many widgets show, subscriptions counted per symbol across widgets. The socket
+ * opens only while the session trades and the tab is visible: it closes 30 s after the tab is hidden
+ * and reconnects with backoff, and every (re)connect gets a fresh snapshot, so gaps fill themselves.
+ * Outside the session the widgets read the last session's bars over REST (cached by the Worker until
+ * the next open). Each device and tab is its own viewer of the person's feed on the server.
+ * While the session is shut they also read the trades since its close (pre-market, after hours,
+ * overnight) once a minute, which the widgets draw after the session.
+ */
+import { EXTENDED_LABEL, } from '@columenlabs/lumen-ui-types/market';
+import { createContext, createElement, useContext, useEffect, useMemo, useState, useSyncExternalStore, } from 'react';
+const HIDDEN_CLOSE_MS = 30_000;
+const CLOSED_CHECK_MS = 60_000;
+/** Folds changed bars into a series (same minute replaced, new ones appended in order). */
+function merge(into, add) {
+    const out = into.slice();
+    for (const b of add) {
+        const i = out.findIndex((x) => x.t === b.t);
+        if (i >= 0)
+            out[i] = b;
+        else {
+            const at = out.findIndex((x) => x.t > b.t);
+            out.splice(at < 0 ? out.length : at, 0, b);
+        }
+    }
+    return out;
+}
+class MarketHub {
+    api;
+    session = null;
+    status = 'loading';
+    error = null;
+    series = new Map();
+    want = new Map();
+    ws = null;
+    backoff = 1000;
+    retryTimer = null;
+    hiddenTimer = null;
+    closedTimer = null;
+    listeners = new Set();
+    version = 0;
+    fetching = null;
+    onVisibility = () => this.visibility();
+    constructor(api) {
+        this.api = api;
+        document.addEventListener('visibilitychange', this.onVisibility);
+    }
+    subscribe = (cb) => {
+        this.listeners.add(cb);
+        return () => this.listeners.delete(cb);
+    };
+    snapshot = () => this.version;
+    changed() {
+        this.version++;
+        for (const l of this.listeners)
+            l();
+    }
+    probe = null;
+    days = new Map();
+    /** Daily breadth and macro series, read once per set of keys per tab (they change once a day). */
+    daily(keys) {
+        const k = keys.join(',');
+        let p = this.days.get(k);
+        if (!p) {
+            p = fetch(`${this.api}/daily?symbols=${encodeURIComponent(k)}`, {
+                credentials: 'same-origin',
+            }).then(async (r) => {
+                if (!r.ok)
+                    throw new Error(`server answered ${r.status}`);
+                return (await r.json()).series;
+            });
+            p.catch(() => this.days.delete(k));
+            this.days.set(k, p);
+        }
+        return p;
+    }
+    /** Whether the app serves market data at all (a 404 means no feed here), read once. */
+    available() {
+        this.probe ??= fetch(`${this.api}/session`, { credentials: 'same-origin' })
+            .then((r) => r.status !== 404)
+            .catch(() => true);
+        return this.probe;
+    }
+    /** A widget shows these symbols; returns its release. */
+    hold(keys) {
+        let added = false;
+        for (const k of keys) {
+            const n = this.want.get(k) ?? 0;
+            this.want.set(k, n + 1);
+            if (!n)
+                added = true;
+        }
+        if (added)
+            this.sync();
+        return () => {
+            for (const k of keys) {
+                const n = (this.want.get(k) ?? 1) - 1;
+                if (n <= 0)
+                    this.want.delete(k);
+                else
+                    this.want.set(k, n);
+            }
+            if (!this.want.size)
+                this.stop();
+            else
+                this.sendSub();
+        };
+    }
+    keys() {
+        return [...this.want.keys()].sort();
+    }
+    /** Reads the session (and its bars when it is not trading), then opens the socket if it trades. */
+    sync() {
+        if (this.ws && this.ws.readyState <= WebSocket.OPEN && this.session?.live) {
+            this.sendSub();
+            return;
+        }
+        if (this.fetching)
+            return;
+        this.fetching = this.read().finally(() => {
+            this.fetching = null;
+            // Symbols a widget added while that read was in flight (the Outlook's tiles mount just after
+            // its chart): read them now. Each is asked once, so a symbol the server leaves out ends as
+            // "No data" instead of a loop.
+            if (!this.session?.live && this.status !== 'error' && this.unasked().length)
+                this.sync();
+        });
+    }
+    /** Symbols asked for and read, so a widget can tell "still loading" from "the server had none". */
+    asked = new Set();
+    unasked() {
+        return this.keys().filter((k) => !this.series.has(k) && !this.asked.has(k));
+    }
+    /** True once `key` was read and the server sent no series for it. */
+    missing(key) {
+        return this.status !== 'loading' && this.asked.has(key) && !this.series.has(key);
+    }
+    /** Reads again after a failure (a widget's Retry). */
+    retry() {
+        for (const k of this.keys())
+            if (!this.series.has(k))
+                this.asked.delete(k);
+        this.status = 'loading';
+        this.error = null;
+        this.changed();
+        this.sync();
+    }
+    async read() {
+        const missing = this.unasked();
+        try {
+            const q = missing.length ? `?symbols=${encodeURIComponent(missing.join(','))}` : '';
+            const res = await fetch(`${this.api}/session${q}`, { credentials: 'same-origin' });
+            if (res.status === 404) {
+                this.status = 'off';
+                this.changed();
+                return;
+            }
+            if (!res.ok)
+                throw new Error(`server answered ${res.status}`);
+            const body = (await res.json());
+            this.session = body.session;
+            this.error = null;
+            for (const s of body.series ?? [])
+                this.series.set(s.key, s);
+            for (const k of missing)
+                this.asked.add(k);
+            if (body.session.live && document.visibilityState === 'visible')
+                this.open();
+            else {
+                this.status = body.session.live ? 'connecting' : 'closed';
+                this.watchClosed();
+                if (!body.session.live)
+                    void this.readExtended();
+            }
+        }
+        catch (e) {
+            this.status = 'error';
+            this.error = e.message;
+        }
+        this.changed();
+    }
+    /** The trades since the session's close, folded into each series (none without a source). */
+    async readExtended() {
+        const keys = this.keys().filter((k) => this.series.has(k));
+        if (!keys.length || this.session?.live)
+            return;
+        const res = await fetch(`${this.api}/extended?symbols=${encodeURIComponent(keys.join(','))}`, {
+            credentials: 'same-origin',
+        }).catch(() => null);
+        if (!res?.ok)
+            return;
+        const body = (await res.json());
+        if (body.session !== this.session?.date)
+            return;
+        for (const [k, extended] of Object.entries(body.extended)) {
+            const s = this.series.get(k);
+            if (s)
+                this.series.set(k, { ...s, extended });
+        }
+        this.changed();
+    }
+    /**
+     * While closed, check once a minute (a cheap read: no bars) whether the session has opened, and
+     * read the trades since the close again.
+     */
+    watchClosed() {
+        if (this.closedTimer)
+            return;
+        this.closedTimer = setInterval(async () => {
+            if (!this.want.size || document.visibilityState !== 'visible')
+                return;
+            const res = await fetch(`${this.api}/session`, { credentials: 'same-origin' }).catch(() => null);
+            const body = res?.ok ? (await res.json()) : null;
+            if (!body)
+                return;
+            if (body.session.date === this.session?.date) {
+                if (!body.session.live)
+                    void this.readExtended();
+                return;
+            }
+            this.series.clear();
+            this.asked.clear();
+            this.sync();
+        }, CLOSED_CHECK_MS);
+    }
+    open() {
+        if (this.closedTimer) {
+            clearInterval(this.closedTimer);
+            this.closedTimer = null;
+        }
+        if (this.ws)
+            return;
+        this.status = 'connecting';
+        const url = new URL(`${this.api}/live`, location.href);
+        url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+        const ws = new WebSocket(url);
+        this.ws = ws;
+        ws.onopen = () => {
+            this.backoff = 1000;
+            this.sendSub();
+        };
+        ws.onmessage = (e) => {
+            let m;
+            try {
+                m = JSON.parse(String(e.data));
+            }
+            catch {
+                return;
+            }
+            if (m.type === 'session') {
+                this.session = m.session;
+                if (!m.session.live) {
+                    // The session closed: drop the socket and read the day's bars instead.
+                    this.close();
+                    this.series.clear();
+                    this.asked.clear();
+                    this.sync();
+                    return;
+                }
+                this.status = 'live';
+            }
+            else if (m.type === 'snapshot') {
+                for (const s of m.series)
+                    this.series.set(s.key, s);
+                this.status = 'live';
+            }
+            else if (m.type === 'bars') {
+                for (const [k, bars] of Object.entries(m.bars)) {
+                    const s = this.series.get(k);
+                    if (s)
+                        this.series.set(k, { ...s, bars: merge(s.bars, bars) });
+                }
+            }
+            this.changed();
+        };
+        ws.onclose = () => {
+            if (this.ws !== ws)
+                return;
+            this.ws = null;
+            if (!this.want.size || document.visibilityState !== 'visible')
+                return;
+            this.status = 'connecting';
+            this.changed();
+            this.retryTimer = setTimeout(() => {
+                this.retryTimer = null;
+                this.sync();
+            }, this.backoff);
+            this.backoff = Math.min(this.backoff * 2, 30_000);
+        };
+    }
+    sendSub() {
+        if (this.ws?.readyState === WebSocket.OPEN)
+            this.ws.send(JSON.stringify({ type: 'sub', symbols: this.keys() }));
+    }
+    close() {
+        const ws = this.ws;
+        this.ws = null;
+        ws?.close(1000, 'done');
+        if (this.retryTimer)
+            clearTimeout(this.retryTimer);
+        this.retryTimer = null;
+    }
+    stop() {
+        this.close();
+        if (this.closedTimer)
+            clearInterval(this.closedTimer);
+        this.closedTimer = null;
+    }
+    visibility() {
+        if (document.visibilityState === 'hidden') {
+            this.hiddenTimer ??= setTimeout(() => {
+                this.hiddenTimer = null;
+                this.close();
+            }, HIDDEN_CLOSE_MS);
+            return;
+        }
+        if (this.hiddenTimer)
+            clearTimeout(this.hiddenTimer);
+        this.hiddenTimer = null;
+        if (this.want.size && !this.ws && this.session?.live)
+            this.sync();
+    }
+}
+/** The trades since the close, scaled to the series (a stand-in ETF to its index), or null. */
+export function extendedOf(s) {
+    const ext = s.extended;
+    const close = s.bars.at(-1)?.c;
+    const lastBar = ext?.bars.at(-1);
+    if (!ext || !lastBar || close === undefined || !ext.base)
+        return null;
+    const k = close / ext.base;
+    return {
+        via: ext.via,
+        close,
+        bars: ext.bars.map((b) => ({ t: b.t, o: b.o * k, h: b.h * k, l: b.l * k, c: b.c * k })),
+        last: lastBar.c * k,
+        at: lastBar.t,
+        label: EXTENDED_LABEL[lastBar.s],
+        /** Change from the session's close, in percent. */
+        change: (lastBar.c / ext.base - 1) * 100,
+    };
+}
+/**
+ * Up or down today: the price now against the close before today's trading. A broker's trading
+ * day starts with the overnight session, so from then on it is the session's close; before (the
+ * session, after hours) it is the prior close.
+ */
+export function todayOf(s) {
+    const ext = extendedOf(s);
+    const close = s.bars.at(-1)?.c;
+    const newDay = s.extended?.bars.some((b) => b.s !== 'post');
+    const base = newDay ? close : s.prevClose;
+    const value = ext?.last ?? close;
+    if (value === undefined || !base)
+        return null;
+    return {
+        value,
+        base,
+        change: (value / base - 1) * 100,
+        label: ext?.label ?? null,
+        at: ext?.at,
+    };
+}
+const MarketContext = createContext(null);
+/** Gives market widgets and the chart dialog live data from `api` (`/api/v1/market`). */
+export function MarketProvider({ api, children }) {
+    const hub = useMemo(() => new MarketHub(api), [api]);
+    return createElement(MarketContext.Provider, { value: hub }, children);
+}
+/** Today's (or the last) session of `symbols`, live while it trades. */
+export function useMarket(symbols) {
+    const hub = useContext(MarketContext);
+    const key = symbols.join(',');
+    useEffect(() => (hub && key ? hub.hold(key.split(',')) : undefined), [hub, key]);
+    useSyncExternalStore(hub?.subscribe ?? (() => () => { }), hub?.snapshot ?? (() => 0), () => 0);
+    if (!hub)
+        return {
+            status: 'off',
+            session: null,
+            series: {},
+            missing: [],
+            error: null,
+            retry: () => { },
+        };
+    const series = {};
+    for (const s of symbols) {
+        const x = hub.series.get(s);
+        if (x)
+            series[s] = x;
+    }
+    return {
+        status: hub.status,
+        session: hub.session,
+        series,
+        missing: symbols.filter((s) => hub.missing(s)),
+        error: hub.error,
+        retry: () => hub.retry(),
+    };
+}
+/** Daily breadth and macro series of `keys` (never live); `error` when they could not be read. */
+export function useMarketDaily(keys) {
+    const hub = useContext(MarketContext);
+    const k = keys.join(',');
+    const [attempt, setAttempt] = useState(0);
+    const [state, setState] = useState({ series: {}, loading: true, error: null });
+    useEffect(() => {
+        if (!hub || !k)
+            return;
+        let on = true;
+        setState((s) => ({ ...s, loading: true, error: null }));
+        void attempt;
+        hub
+            .daily(k.split(','))
+            .then((list) => on &&
+            setState({
+                series: Object.fromEntries(list.map((s) => [s.key, s])),
+                loading: false,
+                error: null,
+            }))
+            .catch((e) => on && setState({ series: {}, loading: false, error: e.message }));
+        return () => {
+            on = false;
+        };
+    }, [hub, k, attempt]);
+    return { ...state, retry: () => setAttempt((n) => n + 1) };
+}
+/** True where a market provider is mounted (an app, suite or not). */
+export const useHasMarket = () => useContext(MarketContext) !== null;
+/** Whether this app has a market feed, without subscribing to anything: null while checking. */
+export function useMarketFeed() {
+    const hub = useContext(MarketContext);
+    const [has, setHas] = useState(hub ? null : false);
+    useEffect(() => {
+        if (!hub)
+            return;
+        let on = true;
+        void hub.available().then((v) => on && setHas(v));
+        return () => {
+            on = false;
+        };
+    }, [hub]);
+    return has;
+}

package/dist/market/lumen-chart.d.ts

@@ -0,0 +1,88 @@
+/**
+ * LumenChart: the one price chart of every app, as a component
+ * (`<LumenChart symbols={[…]} />`, an app's symbol page), the `chart` widget any view can add, and
+ * the chart dialog (mockup "Symbol chart dialog"): any widget, legend name or
+ * symbol on any app opens it. Windows 1D to Max, candles or line, crosshair, drag and zoom,
+ * and the timeline under it. 1D shows today's live bars where the app has live data (an app);
+ * every other window reads history from the app's `bars` route (the warehouse, or Yahoo labelled
+ * Delayed for what the warehouse does not hold).
+ *
+ * Compare: up to 8 symbols. Two or more
+ * draw as % from the left edge of what is visible (dragging the timeline moves the baseline) or as
+ * Price, each on its own scale. Every indicator is made only when added, for one symbol or All
+ * shown: computed ones in the browser from the bars plus warm-up bars before the window (SMA 200
+ * draws from the first bar); P/E, IV and the EPS estimate read once from market data.
+ */
+import type { ChartFormula, IndicatorSpec } from '@columenlabs/lumen-ui-types/chart-formula';
+import { type MarketBar, type MarketWindow } from '@columenlabs/lumen-ui-types/market';
+import { type ReactNode } from 'react';
+import { type LumenLoad } from '../lumen-source.js';
+import { type ChartIndicator } from './indicators.js';
+import { type ChartBar } from './price-chart.js';
+/** Opens the chart dialog: one symbol, or up to 8 to compare, with its indicators if given. */
+export type OpenChart = (symbols: string | string[], indicators?: IndicatorSpec[]) => void;
+/**
+ * The person's saved formulas (Mine): drawn by `mine:<id>`, listed first in the
+ * picker; `save` and `remove` where the app keeps them.
+ */
+export interface MineIndicators {
+    list: ChartIndicator[];
+    save?: (f: ChartFormula) => Promise<void>;
+    remove?: (id: string) => Promise<void>;
+}
+/** Opens the chart dialog; null where no app mounted the dialog. */
+export declare const useSymbolChart: () => OpenChart | null;
+/** The app's history route (`bars`) the chart reads; null where no app mounted the dialog. */
+export declare const useBarsUrl: () => string | null;
+/** Symbols one chart compares at most. */
+export declare const MAX_COMPARE = 8;
+/**
+ * Mounts LumenChart once for an app, and its dialog: `bars` is the app's history route,
+ * `indicators` its sourced indicator route (P/E, IV, EPS estimate); left out, those indicators are
+ * not offered. `mine` is the route of the person's saved formulas; left out, there is no Mine.
+ */
+export declare function SymbolChartProvider({ bars, indicators, mine, children, }: {
+    bars: string;
+    indicators?: string;
+    mine?: string;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare const toChart: (b: MarketBar) => ChartBar;
+/** Daily bars sit at UTC midnight; the chart reads them as days. */
+export declare const toDaily: (b: MarketBar) => ChartBar;
+/** What a LumenChart starts with; key it by them to start it over when they change. */
+export interface LumenChartOptions {
+    /** One symbol, or up to 8 to compare. */
+    symbols: string[];
+    /** The window it opens on; left out: 1D for one symbol, 1Y to compare, 6M for daily series. */
+    window?: MarketWindow;
+    type?: 'candles' | 'line';
+    /**
+     * Indicators drawn for every symbol shown: catalog ids, built-ins with any window (`ema_13`,
+     * `bollinger_20_2p5`), saved formulas (`mine:<id>`) or formulas; left out: SMA 20 and RSI 14 for
+     * one symbol.
+     */
+    indicators?: IndicatorSpec[];
+    /** `dialog` inside the chart dialog; `card` (default) inside a page's card or a sheet. */
+    variant?: 'dialog' | 'card';
+    /** Reads nothing until the chart (`ref`) scrolls into view. */
+    lazy?: boolean;
+    /** Shows a Close button. */
+    onClose?: () => void;
+    /** The window buttons (a card's Window control); left out: shown. */
+    windows?: boolean;
+}
+/** LumenChart as one symbol, or up to 8 compared, inside a card, a sheet or the chart dialog. */
+export declare function LumenChart(props: LumenChartOptions): import("react").JSX.Element;
+/**
+ * LumenChart's state and body, for a card that shows its source: `load` (its ↻ and load time),
+ * `rows` (bars drawn), `ref` (for `lazy`) and `element`. `noDesk`: the app mounted no
+ * SymbolChartProvider, so there is nothing to read.
+ */
+export declare function useLumenChart({ symbols: initial, window: start, type: startType, indicators, variant, lazy, onClose, windows: showWindows, }: LumenChartOptions): {
+    load: LumenLoad;
+    rows: number;
+    ref: (el: Element | null) => void;
+    element: ReactNode;
+    noDesk: boolean;
+};