@columenlabs/lumen-ui 0.0.0-stage → 0.2.0

package/dist/lumen-widget.d.ts

@@ -0,0 +1,614 @@
+import { type CustomViewConfig, type ViewCard, type ViewCardKind, type ViewWidget } from '@columenlabs/lumen-ui-types/views';
+import { type LucideIcon } from 'lucide-react';
+import { type ReactNode } from 'react';
+import { type FilterField } from './lumen-filter.js';
+import { type LinkColor } from './lumen-links.js';
+import { type LumenLoad } from './lumen-source.js';
+import { type ViewDomain, type ViewField } from './view-model.js';
+/** A card's icon, from its kind and style. */
+export declare const cardIcon: (c: {
+    kind: ViewCardKind;
+    style?: string;
+}) => LucideIcon;
+/** The widths a card can take, in columns of the desktop's 6. */
+export declare const CARD_COLUMNS: readonly [1, 2, 3, 4, 5, 6];
+/** The longest name a widget takes. */
+export declare const CARD_TITLE_MAX = 40;
+export declare const cardTitle: (b: ViewCard, viewName: string) => string;
+/** The domain's fields as the filter box reads them, for a card's own tokens. */
+export declare function cardFilterFields<T>(fields: ViewField<T>[]): FilterField<T>[];
+/** A chart, top-N or market widget's body over `rows` (the view's shown rows). */
+export declare function WidgetBody<T>({ card, domain, rows, fields, merge, onDetails, }: {
+    card: ViewCard;
+    domain: ViewDomain<T>;
+    /** Every row of the view (not the table's filter). */
+    rows: T[];
+    fields: FilterField<T>[];
+    /** Folds rows the way the view's flat table does (one line per symbol). */
+    merge: (rows: T[]) => T[];
+    onDetails?: (row: T) => void;
+}): import("react").JSX.Element | null;
+export type CardAction = 'edit' | 'duplicate' | 'up' | 'down' | 'remove';
+/** What LumenLayout gives each of its cards: the layout's edit state and the card's place in it. */
+export interface CardControls {
+    /** The page's layout is being edited. */
+    layout: boolean;
+    /** The person may change this view (an app view is read-only). */
+    editable: boolean;
+    first: boolean;
+    last: boolean;
+    /** A card given its own height by its corner: back to as tall as it draws. */
+    onFit?: () => void;
+    onAction: (a: CardAction) => void;
+    /** A card the page draws itself: it moves and sizes, but has no Edit, Duplicate or Remove. */
+    fixed?: boolean;
+}
+/** A card's link colour on its frame. */
+export interface CardLink {
+    color: LinkColor | null;
+    onPick: (c: LinkColor | null) => void;
+    /** What it follows from other cards' linked chips: `IRA, Roth`. */
+    follows?: string;
+    /** Its own filter's linked chips (the phone's count beside the funnel). */
+    linked?: number;
+}
+export declare function LumenWidget({ id, kind, icon, title, note, controls, tools, filter, filterCount, load, rows, loadNote, pad, pinned, compact, className, children, link: given, help, assistant, strip, shown, style, }: {
+    id: string;
+    /** Its controls (Edit widget ▸ Controls): Ask the assistant, Refresh, Filter box and
+     *  Footer show or hide here; missing keys take the type's default. */
+    shown?: ViewCard['controls'];
+    /** Its style, where it sets the type (a trend's spark or tracker is a Metric). */
+    style?: string;
+    /** ⓘ How to read: a few lines on what the card shows and how to read it,
+     *  opened from the header. */
+    help?: ReactNode;
+    /** ✦ Ask the assistant on every card where the assistant answers: what the assistant needs beyond the
+     *  card's title to read it ("Tune tn_… of playbook …: read it with tune_read"); false: no button. */
+    assistant?: string | false;
+    /** Its link colour: the square before the title, what it follows after it,
+     *  and how many of its filter's chips are linked. Left out: the page's colour for `id` (every
+     *  card carries the square); false: none (a form, with no data to link). */
+    link?: CardLink | false;
+    /** The card's kind; null for a card a page builds in code (not in the view's config). */
+    kind: ViewCardKind | null;
+    icon?: LucideIcon;
+    title: string;
+    note?: ReactNode;
+    /** Left out: a card the layout cannot edit. */
+    controls?: CardControls;
+    /** Buttons before the ↻, e.g. a view's pager. */
+    tools?: ReactNode;
+    /** The card's own filter (a view's LumenTokenizedFilter and Group): on the title's line
+     *  when the header is wide, on a line under it when narrow, behind a funnel button on phone. */
+    filter?: ReactNode;
+    /** Active filter tokens, the count on the phone's funnel button. */
+    filterCount?: number;
+    /**
+     * A line under the header and filter (widget anatomy zone 4): what the card
+     * follows, or an offer such as Link to Holdings by Symbol.
+     */
+    strip?: ReactNode;
+    /** The card's source: its ↻, and its load time below the body. */
+    load?: LumenLoad;
+    rows?: number;
+    /** Said in the load line instead of rows, e.g. "from the view's rows". */
+    loadNote?: string;
+    pad?: boolean;
+    /** The header stays in sight while a wide view scrolls sideways under it. */
+    pinned?: boolean;
+    /** A LumenCard (one number): its title is a small label over the number, no rule under it. */
+    compact?: boolean;
+    className?: string;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * One widget in its card. Widgets over the view's rows (tiles,
+ * charts, top N) load with the view: its states, its ↻. Market and price chart widgets read their own
+ * data and start once their card scrolls into view.
+ */
+export declare function LumenSavedWidget<T>({ widget, title, domain, rows, fields, merge, onDetails, load, tiles, controls, link, }: {
+    widget: ViewWidget;
+    /** Its link colour and what it follows (the layout narrows `rows` by it). */
+    link?: CardLink;
+    title: string;
+    domain: ViewDomain<T>;
+    /** Every row of the view (not the table's filter). */
+    rows: T[];
+    fields: FilterField<T>[];
+    /** Folds rows the way the view's flat table does (one line per symbol). */
+    merge: (rows: T[]) => T[];
+    onDetails?: (row: T) => void;
+    /** The view's rows' loading state, for widgets drawn from them. */
+    load?: LumenLoad;
+    /** The tiles widget's tiles, drawn by the layout. */
+    tiles?: ReactNode;
+    controls?: CardControls;
+}): import("react").JSX.Element;
+/** The page header's layout slot while a page's layout is edited: Add widget, Cancel and Save,
+ *  icons only (in the header, not a bar of their own: Cancel
+ *  drops the changes and leaves, in place of Reset). */
+export declare function LayoutActions({ onCancel, onAdd, onSave, onReset, }: {
+    onCancel: () => void;
+    onAdd: () => void;
+    onSave: () => void;
+    /** A built-in page the person changed: puts it back to its default. */
+    onReset?: () => void;
+}): import("react").JSX.Element;
+/** The chip beside the title while a page's layout is edited. */
+export declare function LayoutChip(): import("react").JSX.Element;
+/** An id not yet used in `cards`: `base`, else `base_2`, `base_3`... */
+export declare function freeId(cards: ViewCard[], base: string): string;
+/** A new card of a style (`kind:style`) with sensible fields of this domain. */
+export declare function draftOf<T>(styleId: string, domain: ViewDomain<T>, cards: ViewCard[]): ViewCard;
+/** Whether the app can draw a style: Market needs its live feed, Price its history route, Growth
+ *  of $1 a domain that draws curves. */
+export declare function useOffered<T>(domain: ViewDomain<T>): (styleId: string) => boolean;
+/** Add widget: the domain's pre-built widgets, or a kind to build. */
+export declare function AddWidgetDialog<T>({ open, onOpenChange, domain, cards, onAdd, onBuild, }: {
+    open: boolean;
+    onOpenChange: (o: boolean) => void;
+    domain: ViewDomain<T>;
+    cards: ViewCard[];
+    /** Adds a ready card (a pre-built widget, or the view's tiles or the view itself). */
+    onAdd: (card: ViewCard) => void;
+    /** Opens Edit widget on a new card of a kind. */
+    onBuild: (card: ViewCard) => void;
+}): import("react").JSX.Element;
+/** A page's cards after `action` on card `i`, or null for Edit (the caller opens a dialog). */
+export declare function cardsAfter(cards: ViewCard[], i: number, action: CardAction): ({
+    id: string;
+    title: string | null;
+    w: number;
+    h?: number | undefined;
+    x?: number | undefined;
+    y?: number | undefined;
+    phone?: {
+        x: number;
+        y: number;
+        w: number;
+        h?: number | undefined;
+    } | undefined;
+    filter: {
+        key: string;
+        value: string;
+        not?: boolean | undefined;
+        op?: "between" | "eq" | "gt" | "lt" | undefined;
+        link?: "amber" | "blue" | "lime" | "pink" | "teal" | undefined;
+    }[];
+    link?: "amber" | "blue" | "lime" | "pink" | "teal" | undefined;
+    controls?: Partial<Record<"ask" | "columns" | "download" | "filter" | "footer" | "group" | "header" | "legend" | "pager" | "refresh" | "window", boolean>> | undefined;
+    kind: "table";
+    style: "table";
+    table?: {
+        shape: "group" | "pivot" | "table";
+        columns: string[];
+        hidden?: string[] | undefined;
+        chips: {
+            key: string;
+            placement: "column" | "inline";
+        }[];
+        formats?: Record<string, "compact" | "integer" | "number" | "percent" | "price" | "price_rounded" | "price_signed" | "rounded" | "signed" | "weight"> | undefined;
+        aggs?: Record<string, "count" | "distinct" | "first" | "last" | "max" | "mean" | "min" | "none" | "sum"> | undefined;
+        group: {
+            fields: string[];
+            default: string | null;
+        };
+        subgroup?: string | null | undefined;
+        pivot: {
+            rows: string;
+            columns: string;
+            value: string;
+            agg: "count" | "distinct" | "first" | "last" | "max" | "mean" | "min" | "sum";
+        } | null;
+        sort: {
+            key: string;
+            desc: boolean;
+        } | null;
+        pagination: {
+            on: boolean;
+            size: 25 | 50 | 100 | 250;
+        };
+        width?: "fit" | "scroll" | undefined;
+    } | undefined;
+} | {
+    id: string;
+    title: string | null;
+    w: number;
+    h?: number | undefined;
+    x?: number | undefined;
+    y?: number | undefined;
+    phone?: {
+        x: number;
+        y: number;
+        w: number;
+        h?: number | undefined;
+    } | undefined;
+    filter: {
+        key: string;
+        value: string;
+        not?: boolean | undefined;
+        op?: "between" | "eq" | "gt" | "lt" | undefined;
+        link?: "amber" | "blue" | "lime" | "pink" | "teal" | undefined;
+    }[];
+    link?: "amber" | "blue" | "lime" | "pink" | "teal" | undefined;
+    controls?: Partial<Record<"ask" | "columns" | "download" | "filter" | "footer" | "group" | "header" | "legend" | "pager" | "refresh" | "window", boolean>> | undefined;
+    kind: "table";
+    style: "top_n";
+    sort: string;
+    desc: boolean;
+    n: number;
+    columns: string[];
+} | {
+    id: string;
+    title: string | null;
+    h?: number | undefined;
+    x?: number | undefined;
+    y?: number | undefined;
+    phone?: {
+        x: number;
+        y: number;
+        w: number;
+        h?: number | undefined;
+    } | undefined;
+    filter: {
+        key: string;
+        value: string;
+        not?: boolean | undefined;
+        op?: "between" | "eq" | "gt" | "lt" | undefined;
+        link?: "amber" | "blue" | "lime" | "pink" | "teal" | undefined;
+    }[];
+    link?: "amber" | "blue" | "lime" | "pink" | "teal" | undefined;
+    controls?: Partial<Record<"ask" | "columns" | "download" | "filter" | "footer" | "group" | "header" | "legend" | "pager" | "refresh" | "window", boolean>> | undefined;
+    kind: "metric";
+    style: "number" | "progress_bar" | "progress_circle";
+    w: number;
+    tile: {
+        key: string;
+        label: string;
+        field: string;
+        agg: "count" | "distinct" | "first" | "last" | "max" | "mean" | "min" | "sum";
+        filter: {
+            key: string;
+            value: string;
+            not?: boolean | undefined;
+            op?: "between" | "eq" | "gt" | "lt" | undefined;
+            link?: "amber" | "blue" | "lime" | "pink" | "teal" | undefined;
+        }[];
+        sign: boolean;
+        suffix: string;
+        lines: ({
+            kind: "value";
+            field: string;
+            agg: "count" | "distinct" | "first" | "last" | "max" | "mean" | "min" | "sum";
+            filter: {
+                key: string;
+                value: string;
+                not?: boolean | undefined;
+                op?: "between" | "eq" | "gt" | "lt" | undefined;
+                link?: "amber" | "blue" | "lime" | "pink" | "teal" | undefined;
+            }[];
+            suffix: string;
+        } | {
+            kind: "pct";
+            field: string;
+            agg: "count" | "distinct" | "first" | "last" | "max" | "mean" | "min" | "sum";
+        } | {
+            kind: "text";
+            text: string;
+        })[];
+    } | {
+        key: string;
+    };
+    target?: number | undefined;
+    meter?: "health" | "usage" | undefined;
+    bands?: {
+        warn: number;
+        bad: number;
+    } | undefined;
+} | {
+    id: string;
+    title: string | null;
+    w: number;
+    h?: number | undefined;
+    x?: number | undefined;
+    y?: number | undefined;
+    phone?: {
+        x: number;
+        y: number;
+        w: number;
+        h?: number | undefined;
+    } | undefined;
+    filter: {
+        key: string;
+        value: string;
+        not?: boolean | undefined;
+        op?: "between" | "eq" | "gt" | "lt" | undefined;
+        link?: "amber" | "blue" | "lime" | "pink" | "teal" | undefined;
+    }[];
+    link?: "amber" | "blue" | "lime" | "pink" | "teal" | undefined;
+    controls?: Partial<Record<"ask" | "columns" | "download" | "filter" | "footer" | "group" | "header" | "legend" | "pager" | "refresh" | "window", boolean>> | undefined;
+    kind: "metric";
+    style: "row";
+    tiles?: ({
+        key: string;
+        label: string;
+        field: string;
+        agg: "count" | "distinct" | "first" | "last" | "max" | "mean" | "min" | "sum";
+        filter: {
+            key: string;
+            value: string;
+            not?: boolean | undefined;
+            op?: "between" | "eq" | "gt" | "lt" | undefined;
+            link?: "amber" | "blue" | "lime" | "pink" | "teal" | undefined;
+        }[];
+        sign: boolean;
+        suffix: string;
+        lines: ({
+            kind: "value";
+            field: string;
+            agg: "count" | "distinct" | "first" | "last" | "max" | "mean" | "min" | "sum";
+            filter: {
+                key: string;
+                value: string;
+                not?: boolean | undefined;
+                op?: "between" | "eq" | "gt" | "lt" | undefined;
+                link?: "amber" | "blue" | "lime" | "pink" | "teal" | undefined;
+            }[];
+            suffix: string;
+        } | {
+            kind: "pct";
+            field: string;
+            agg: "count" | "distinct" | "first" | "last" | "max" | "mean" | "min" | "sum";
+        } | {
+            kind: "text";
+            text: string;
+        })[];
+    } | {
+        key: string;
+    })[] | undefined;
+    rank?: string | undefined;
+    cash?: boolean | undefined;
+} | {
+    id: string;
+    title: string | null;
+    h?: number | undefined;
+    x?: number | undefined;
+    y?: number | undefined;
+    phone?: {
+        x: number;
+        y: number;
+        w: number;
+        h?: number | undefined;
+    } | undefined;
+    filter: {
+        key: string;
+        value: string;
+        not?: boolean | undefined;
+        op?: "between" | "eq" | "gt" | "lt" | undefined;
+        link?: "amber" | "blue" | "lime" | "pink" | "teal" | undefined;
+    }[];
+    link?: "amber" | "blue" | "lime" | "pink" | "teal" | undefined;
+    controls?: Partial<Record<"ask" | "columns" | "download" | "filter" | "footer" | "group" | "header" | "legend" | "pager" | "refresh" | "window", boolean>> | undefined;
+    w: number;
+    date: string;
+    values: string[];
+    bucket: "day" | "month" | "week" | "year";
+    agg: "count" | "last" | "mean" | "sum";
+    kind: "metric";
+    style: "spark" | "tracker";
+} | {
+    id: string;
+    title: string | null;
+    w: number;
+    h?: number | undefined;
+    x?: number | undefined;
+    y?: number | undefined;
+    phone?: {
+        x: number;
+        y: number;
+        w: number;
+        h?: number | undefined;
+    } | undefined;
+    filter: {
+        key: string;
+        value: string;
+        not?: boolean | undefined;
+        op?: "between" | "eq" | "gt" | "lt" | undefined;
+        link?: "amber" | "blue" | "lime" | "pink" | "teal" | undefined;
+    }[];
+    link?: "amber" | "blue" | "lime" | "pink" | "teal" | undefined;
+    controls?: Partial<Record<"ask" | "columns" | "download" | "filter" | "footer" | "group" | "header" | "legend" | "pager" | "refresh" | "window", boolean>> | undefined;
+    kind: "allocation";
+    style: "bar";
+    by: string;
+    value: string;
+    max: number;
+} | {
+    id: string;
+    title: string | null;
+    w: number;
+    h?: number | undefined;
+    x?: number | undefined;
+    y?: number | undefined;
+    phone?: {
+        x: number;
+        y: number;
+        w: number;
+        h?: number | undefined;
+    } | undefined;
+    filter: {
+        key: string;
+        value: string;
+        not?: boolean | undefined;
+        op?: "between" | "eq" | "gt" | "lt" | undefined;
+        link?: "amber" | "blue" | "lime" | "pink" | "teal" | undefined;
+    }[];
+    link?: "amber" | "blue" | "lime" | "pink" | "teal" | undefined;
+    controls?: Partial<Record<"ask" | "columns" | "download" | "filter" | "footer" | "group" | "header" | "legend" | "pager" | "refresh" | "window", boolean>> | undefined;
+    kind: "allocation";
+    style: "donut";
+    by: string;
+    value: string;
+    max: number;
+} | {
+    id: string;
+    title: string | null;
+    w: number;
+    h?: number | undefined;
+    x?: number | undefined;
+    y?: number | undefined;
+    phone?: {
+        x: number;
+        y: number;
+        w: number;
+        h?: number | undefined;
+    } | undefined;
+    filter: {
+        key: string;
+        value: string;
+        not?: boolean | undefined;
+        op?: "between" | "eq" | "gt" | "lt" | undefined;
+        link?: "amber" | "blue" | "lime" | "pink" | "teal" | undefined;
+    }[];
+    link?: "amber" | "blue" | "lime" | "pink" | "teal" | undefined;
+    controls?: Partial<Record<"ask" | "columns" | "download" | "filter" | "footer" | "group" | "header" | "legend" | "pager" | "refresh" | "window", boolean>> | undefined;
+    kind: "allocation";
+    style: "bar_list";
+    by: string;
+    value: string;
+    signed: boolean;
+    stack?: string | undefined;
+    desc: boolean;
+    n: number;
+} | {
+    id: string;
+    title: string | null;
+    w: number;
+    h?: number | undefined;
+    x?: number | undefined;
+    y?: number | undefined;
+    phone?: {
+        x: number;
+        y: number;
+        w: number;
+        h?: number | undefined;
+    } | undefined;
+    filter: {
+        key: string;
+        value: string;
+        not?: boolean | undefined;
+        op?: "between" | "eq" | "gt" | "lt" | undefined;
+        link?: "amber" | "blue" | "lime" | "pink" | "teal" | undefined;
+    }[];
+    link?: "amber" | "blue" | "lime" | "pink" | "teal" | undefined;
+    controls?: Partial<Record<"ask" | "columns" | "download" | "filter" | "footer" | "group" | "header" | "legend" | "pager" | "refresh" | "window", boolean>> | undefined;
+    kind: "chart";
+    style: "price";
+    symbol: string;
+    window: "1D" | "1M" | "1Y" | "5D" | "5Y" | "6M" | "Max" | "YTD";
+    type: "candles" | "line";
+} | {
+    id: string;
+    title: string | null;
+    w: number;
+    h?: number | undefined;
+    x?: number | undefined;
+    y?: number | undefined;
+    phone?: {
+        x: number;
+        y: number;
+        w: number;
+        h?: number | undefined;
+    } | undefined;
+    filter: {
+        key: string;
+        value: string;
+        not?: boolean | undefined;
+        op?: "between" | "eq" | "gt" | "lt" | undefined;
+        link?: "amber" | "blue" | "lime" | "pink" | "teal" | undefined;
+    }[];
+    link?: "amber" | "blue" | "lime" | "pink" | "teal" | undefined;
+    controls?: Partial<Record<"ask" | "columns" | "download" | "filter" | "footer" | "group" | "header" | "legend" | "pager" | "refresh" | "window", boolean>> | undefined;
+    kind: "chart";
+    style: "growth";
+    scale: "linear" | "log";
+} | {
+    id: string;
+    title: string | null;
+    w: number;
+    h?: number | undefined;
+    x?: number | undefined;
+    y?: number | undefined;
+    phone?: {
+        x: number;
+        y: number;
+        w: number;
+        h?: number | undefined;
+    } | undefined;
+    filter: {
+        key: string;
+        value: string;
+        not?: boolean | undefined;
+        op?: "between" | "eq" | "gt" | "lt" | undefined;
+        link?: "amber" | "blue" | "lime" | "pink" | "teal" | undefined;
+    }[];
+    link?: "amber" | "blue" | "lime" | "pink" | "teal" | undefined;
+    controls?: Partial<Record<"ask" | "columns" | "download" | "filter" | "footer" | "group" | "header" | "legend" | "pager" | "refresh" | "window", boolean>> | undefined;
+    kind: "chart";
+    style: "market";
+    symbols: string[];
+    layout: "lines" | "tiles" | "today";
+} | {
+    id: string;
+    title: string | null;
+    h?: number | undefined;
+    x?: number | undefined;
+    y?: number | undefined;
+    phone?: {
+        x: number;
+        y: number;
+        w: number;
+        h?: number | undefined;
+    } | undefined;
+    filter: {
+        key: string;
+        value: string;
+        not?: boolean | undefined;
+        op?: "between" | "eq" | "gt" | "lt" | undefined;
+        link?: "amber" | "blue" | "lime" | "pink" | "teal" | undefined;
+    }[];
+    link?: "amber" | "blue" | "lime" | "pink" | "teal" | undefined;
+    controls?: Partial<Record<"ask" | "columns" | "download" | "filter" | "footer" | "group" | "header" | "legend" | "pager" | "refresh" | "window", boolean>> | undefined;
+    w: number;
+    date: string;
+    values: string[];
+    bucket: "day" | "month" | "week" | "year";
+    agg: "count" | "last" | "mean" | "sum";
+    kind: "chart";
+    style: "area" | "bars" | "combo" | "line" | "stacked";
+} | {
+    id: string;
+    title: string | null;
+    w: number;
+    h?: number | undefined;
+    x?: number | undefined;
+    y?: number | undefined;
+    phone?: {
+        x: number;
+        y: number;
+        w: number;
+        h?: number | undefined;
+    } | undefined;
+    filter: {
+        key: string;
+        value: string;
+        not?: boolean | undefined;
+        op?: "between" | "eq" | "gt" | "lt" | undefined;
+        link?: "amber" | "blue" | "lime" | "pink" | "teal" | undefined;
+    }[];
+    link?: "amber" | "blue" | "lime" | "pink" | "teal" | undefined;
+    controls?: Partial<Record<"ask" | "columns" | "download" | "filter" | "footer" | "group" | "header" | "legend" | "pager" | "refresh" | "window", boolean>> | undefined;
+    kind: "page";
+    amount?: number | undefined;
+})[] | null;
+export type { CustomViewConfig };