@columenlabs/lumen-ui 0.0.0-stage → 0.1.1

package/dist/view-model.d.ts

@@ -0,0 +1,390 @@
+import type { JoinKey } from '@columenlabs/lumen-ui-types/domains';
+import { type CustomViewConfig, type ViewAgg, type ViewChip, type ViewFormat, type ViewTotalAgg } from '@columenlabs/lumen-ui-types/views';
+import type { LucideIcon } from 'lucide-react';
+import type { ReactNode } from 'react';
+import type { ChartBand, ChartMarker, Series } from './growth-chart.js';
+export type ViewCellValue = number | string | null;
+/** One field of a data domain: how to read it, show it, filter, group and roll it up. */
+export interface ViewField<T> {
+    key: string;
+    label: string;
+    icon: LucideIcon;
+    value: (row: T) => ViewCellValue;
+    /**
+     * Its name in formulas when not `<domain>.<key>`: a join field's
+     * `symbol.price`, a frame column's `frame.<frame>.<column>`, a linked domain's `tax_lots.count`.
+     */
+    name?: string;
+    /**
+     * Where the field comes from: one of the domain's `groups` (Holding, Symbol,
+     * Account). The editor's tree and the table's column-group headers follow it; formulas are their
+     * own group. Left out: the domain's first group.
+     */
+    group?: string;
+    /** The sub-heading within its group in the editor's tree (Valuation, Analysts, Technicals). */
+    topic?: string;
+    /** Every value a row has for filtering, when it has several (a symbol in Holdings and Watchlist). */
+    values?: (row: T) => string[];
+    format: ViewFormat;
+    /** How the value is made, shown under the field in the Edit dialog. */
+    formula?: string;
+    /** A holding amount (dollars or size) that Hide amounts masks. */
+    amount?: boolean;
+    /** Large numbers in short form, $283.1B or 6.1M (13F funds). */
+    compact?: boolean;
+    /** What an empty cell says (`N/A` where the source has no value for it); left out: a dash. */
+    empty?: string;
+    /** A short note beside the field in the Edit dialog, e.g. `per ticker`. */
+    note?: string;
+    /**
+     * Makes the cell editable: a click picks a value in use or takes a new one,
+     * saved through `save`; `note` says what an edit covers for that row. `options` lists every
+     * value the field has, in use or not, so the picker offers them whatever the filter shows
+     *; without it the picker offers the values in the shown rows.
+     */
+    edit?: {
+        /** Saves one value (null clears it). A field with `many` leaves it out. */
+        save?: (row: T, value: string | null) => Promise<unknown>;
+        /**
+         * Several values a row (labels): the cell shows each of `values` as a chip
+         * and its picker ticks any number, typed names added, saved together when it closes.
+         */
+        many?: (row: T, values: string[]) => Promise<unknown>;
+        note?: (row: T) => string;
+        options?: () => {
+            inUse: string[];
+            unused: string[];
+        };
+        /**
+         * Typed in place (Edits in place): the cell is a number or text box, as in
+         * a sheet (click or tap and type; Enter saves, Esc leaves, Tab moves right), not a picker.
+         */
+        input?: 'number' | 'text';
+        /** The picker offers only `options`, with no typed new value (an app, an area). */
+        fixed?: boolean;
+        /** This row's cell was typed by hand: a small ✎ marks it. */
+        edited?: (row: T) => boolean;
+    };
+    /** Offered as `field:value` tokens in the filter box. */
+    filterable?: boolean;
+    /** Offered in the Group switcher and as pivot rows or columns. */
+    groupable?: boolean;
+    /** Why a field is not groupable, shown on its greyed Group box in Edit view, e.g. `One per holding. Group by Underlying.` */
+    groupNote?: string;
+    /** How group, pivot and Total rows roll the field up; no roll-up when left out. */
+    aggregate?: ViewAgg;
+    /** A formula column with no `aggregate`: group and Total rows run `compute` over the rows' roll-ups of its inputs. */
+    rollFormula?: boolean;
+    /** Group and Total rows leave it blank (the view picked None for it). */
+    noRollup?: boolean;
+    /** A value the page works out from the row and the shown rows (a formula column). */
+    compute?: (row: T, scope: {
+        value: (key: string) => ViewCellValue;
+        groupSum: (key: string) => number;
+        totalSum: (key: string) => number;
+    }) => ViewCellValue;
+    /**
+     * A share the page works out, in %: the row's `of` field over its sum in the row's group
+     * (`group`; every shown row when not grouped) or in every shown row (`total`). A group row shows
+     * its group's share of the total. `value` is unused for it.
+     */
+    share?: {
+        of: string;
+        within: 'group' | 'total';
+    };
+    /** Draws the cell instead of its formatted value (a sparkline); sorting and filters still use
+     *  `value` (strategy lab). */
+    render?: (row: T) => ReactNode;
+    /** The ticker a click on the cell charts in the app's chart dialog (an option charts its
+     *  underlying); null leaves the row's cell plain. */
+    chart?: (row: T) => string | null;
+    /** The chip's colour when the field shows as a chip: `gain` green, `muted` grey (Open and
+     *  Closed lots), `loss` red and `info` blue (a run's Failed and Running;
+     *  `RUN_STATE_TONE`). Left out: the plain chip. */
+    tone?: (row: T) => ViewChipTone | undefined;
+    /**
+     * A text value's colour (a category's, a label's): a dot before it in the
+     * cell, its chip and the edit picker. A CSS colour; a theme token reads in light and dark.
+     */
+    color?: (value: string) => string | undefined;
+    /** The cell's background, a theme colour mix (a P/L heat grid). */
+    tint?: (row: T) => string | undefined;
+    /** Left out on phones, where the table has no room for it (a returns table's longer windows). */
+    hideOnPhone?: boolean;
+    /**
+     * How the value updates (live domains): `live` moves with the market while it
+     * trades (a quote), `asof` is a daily or snapshot value (a close, a fact, the assistant frame's column).
+     * `calc` is worked out from live values the domain has no field for (an account's value).
+     * Left out it is fixed (a quantity, a cost), unless `from` names a live field.
+     */
+    updates?: 'live' | 'calc' | 'asof';
+    /** The fields it is worked out from, so a value made from a live one marks as Live calc. */
+    from?: string[];
+}
+export type ViewChipTone = 'gain' | 'loss' | 'info' | 'muted' | 'sky' | 'amber';
+/** A chip's classes per tone, on the theme's tokens so light and dark both read. */
+export declare const CHIP_TONE: Record<ViewChipTone, string>;
+/** A run's state as a chip, the same on every app: done green, failed
+ *  red, running blue, queued, waiting and canceled grey. */
+export declare const RUN_STATE_TONE: {
+    readonly done: "gain";
+    readonly failed: "loss";
+    readonly running: "info";
+    readonly queued: "muted";
+    readonly waiting: "muted";
+    readonly canceled: "muted";
+};
+/** A group of fields by where they come from: their colour and, per topic, the source line. */
+export interface ViewFieldGroup {
+    id: string;
+    label: string;
+    /** A theme colour (`var(--chart-3)`) for the group's dot and column-group header. */
+    color?: string;
+    /** What the group's fields are looked up by, e.g. `by symbol · an option by its underlying`. */
+    note?: string;
+    /** Each topic's source, e.g. Feed, live (`JOIN_SOURCES`). */
+    sources?: Record<string, ViewSource & {
+        detail?: string;
+    }>;
+}
+/** Where a topic's fields come from; its colour marks the topic in the field tree. */
+export interface ViewSource {
+    name: string;
+    /** A theme colour (`var(--chart-2)`), one per source across every app. */
+    color: string;
+}
+/** The formulas group: a view's own formula columns. */
+export declare const FORMULAS_GROUP = "_formulas";
+/** A data domain: registered once, any app can open views on it. */
+export interface ViewDomain<T> {
+    id: string;
+    fields: ViewField<T>[];
+    /** Field groups in order; without them every field is one group. */
+    groups?: ViewFieldGroup[];
+    /**
+     * The keys its rows carry (views from data domains): a reader per key, null
+     * for a row without one (cash). The shell's `useJoins` attaches the registry's join fields for
+     * each key (symbol: Price, Valuation, Technicals, Change...; account: Brokerage, Trading, Cash)
+     * on any card of any app, after the domain's own fields; an own field of the same key wins.
+     */
+    keys?: Partial<Record<JoinKey, (row: T) => string | string[] | null>>;
+    /** A stable id per row (React keys, the details drawer). */
+    rowKey: (row: T) => string;
+    /** Free text the filter box matches besides field values (a name, an id). */
+    text?: (row: T) => string[];
+    /** False keeps views from adding their own formula columns (`config.formulas`); every other
+     *  domain takes them (formulas everywhere, `takesFormulas`). */
+    formulas?: false;
+    /** The domain's own summary tiles a view can show, in the order offered;
+     *  the app draws them (LumenLayout's `tile`). */
+    tiles?: {
+        key: string;
+        label: string;
+        icon: LucideIcon;
+    }[];
+    /**
+     * Row-tap filtering (the assistant drafts step 1): in a card with a link colour, a row
+     * tap picks the row's value of this field as a temporary linked chip, so every card of that
+     * colour narrows to it (tap a lot, see its swaps); a second tap lets go. Unlinked, a tap opens the
+     * row as usual.
+     */
+    rowLink?: string;
+    /** The details drawer: collapsible sections (the shell's DrawerSection), each with its icon.
+     *  A section starts collapsed unless `open` says so; a function opens it only for rows it
+     *  holds something for. `count` and `hint` fill the header's chip and note. */
+    details?: {
+        id: string;
+        label: string;
+        icon: LucideIcon;
+        open?: boolean | ((row: T) => boolean);
+        count?: (row: T) => number | null;
+        hint?: (row: T) => string | null;
+        render: (row: T) => ReactNode;
+    }[];
+    /** While grouped, rows of one group sharing `key` show as one line, made by `rows`. */
+    merge?: {
+        key: (row: T) => string;
+        rows: (rows: T[]) => T;
+    };
+    /** A folded row's own rows, shown as a table at the top of its details drawer, first column
+     *  `by` (the field they differ on), then the view's columns. */
+    parts?: {
+        label: string;
+        by: string;
+        rows: (row: T) => T[];
+        /** `rows` are the other rows only, not the row itself, so one is enough to open (a post's repeats). By default they include it and need two. */
+        others?: boolean;
+    };
+    /**
+     * A row with more to read opens it in a panel inside the table, right under the row, from the
+     * chevron in its first cell (an outlook's write-up, an article's summary).
+     * `render` returns null for rows with nothing more: they get no chevron. Takes the chevron over
+     * from the sub-group.
+     */
+    panel?: {
+        label: string;
+        render: (row: T) => ReactNode | null;
+    };
+    /**
+     * What a row can open under it, one level: the view's "Each row opens"
+     * picks one, or none; a view that says nothing opens the first. Either `rows`, a row's own
+     * children (tax lots, accounts, variants), or `under`, where rows sharing that key fold into one
+     * rolled-up line that opens them (holdings by underlying: Shares, then each option). `name`
+     * labels each child in the first column.
+     */
+    subgroups?: ViewSubgroup<T>[];
+    /**
+     * Curves for the Growth of $1 widget: the shown rows' lines (rows with no
+     * curve yet drop out) and anything drawn beside them (benchmarks), the bands (an OOS window, its
+     * line draggable) and markers, the card's header tools and a note. Only domains with it offer
+     * the widget.
+     */
+    growth?: {
+        lines: (rows: T[]) => Series[];
+        bands?: (rows: T[]) => ChartBand[];
+        markers?: ChartMarker[];
+        tools?: ReactNode;
+        note?: string;
+        /** The curves' own loading (the tapes), when they load apart from the rows. */
+        loading?: boolean;
+    };
+    /**
+     * The tiles card's own header from the shown rows: say whose numbers the
+     * tiles show and how that row was picked, e.g. "Best variant: Daily close" / "highest CAGR", and
+     * its own tools (a Rank by picker).
+     */
+    tilesHead?: (rows: T[]) => {
+        title?: string;
+        note?: string;
+        tools?: ReactNode;
+    };
+    /**
+     * The domain's cash rows (an account's cash line), when it has them: each
+     * Summary then offers Include cash in Edit widget (`summaryCash`).
+     */
+    cash?: (row: T) => boolean;
+}
+/** Whether a Summary counts the domain's cash rows: its own choice, else only when it covers
+ *  every row (no filter of its own, no linked chips). */
+export declare const summaryCash: (card: {
+    cash?: boolean;
+}, narrowed: boolean) => boolean;
+/** One choice of a domain's "Each row opens". */
+export interface ViewSubgroup<T> {
+    key: string;
+    label: string;
+    icon: LucideIcon;
+    rows?: (row: T) => T[];
+    under?: (row: T) => string;
+    name?: (row: T) => string;
+    /** `under` folds a key even when one row has it (a field's second level of grouping). */
+    always?: boolean;
+}
+/**
+ * What a row can open: the domain's own sub-groups, else every groupable field as a second level
+ * of grouping (the assistant frame tab groups by class, then by unit). The field's
+ * rows sharing a value fold into one rolled-up line that opens them.
+ */
+/** The picker's name: a domain's own sub-groups open rows, field ones group a second level. */
+export declare function subgroupLabel<T>(domain: ViewDomain<T>): string;
+export declare function subgroupsOf<T>(domain: ViewDomain<T>): ViewSubgroup<T>[];
+/** The sub-group a view opens: its own pick, else the domain's first; null for none. */
+export declare function subgroupOf<T>(domain: ViewDomain<T>, key: string | null | undefined): ViewSubgroup<T> | null;
+/** Rolls values up; nulls are skipped and an empty set is null (count is 0). */
+export declare function rollUp(values: ViewCellValue[], agg: ViewAgg): ViewCellValue;
+/** A view's chip fields and where each shows; views saved before chips existed have none. */
+export declare const chipsOf: (c: CustomViewConfig) => ViewChip[];
+/** Whether views over the domain may add formula columns: every domain but one that opts out. */
+export declare const takesFormulas: (domain: {
+    formulas?: false;
+}) => boolean;
+/** A view's formula columns; views saved before formulas existed have none. */
+export declare const formulasOf: (c: CustomViewConfig) => {
+    key: string;
+    label: string;
+    expr: string;
+    format: "number" | "text" | "weight" | "compact" | "rounded" | "price" | "price_rounded" | "price_signed" | "percent" | "signed" | "integer";
+    agg: "none" | "max" | "min" | "first" | "last" | "sum" | "count" | "mean" | "distinct" | null;
+}[];
+/** Fields listed under Columns but not shown, for their Filter and Group ticks; views saved before it have none. */
+export declare const hiddenOf: (c: CustomViewConfig) => string[];
+/** A view's own tiles; views saved before tiles existed have none. */
+export declare const tilesOf: (c: CustomViewConfig) => ({
+    key: string;
+    label: string;
+    field: string;
+    agg: "max" | "min" | "first" | "last" | "sum" | "count" | "mean" | "distinct";
+    filter: {
+        key: string;
+        value: string;
+        not?: boolean | undefined;
+        op?: "gt" | "lt" | "eq" | "between" | undefined;
+        link?: "blue" | "lime" | "pink" | "teal" | "amber" | undefined;
+    }[];
+    sign: boolean;
+    suffix: string;
+    lines: ({
+        kind: "value";
+        field: string;
+        agg: "max" | "min" | "first" | "last" | "sum" | "count" | "mean" | "distinct";
+        filter: {
+            key: string;
+            value: string;
+            not?: boolean | undefined;
+            op?: "gt" | "lt" | "eq" | "between" | undefined;
+            link?: "blue" | "lime" | "pink" | "teal" | "amber" | undefined;
+        }[];
+        suffix: string;
+    } | {
+        kind: "pct";
+        field: string;
+        agg: "max" | "min" | "first" | "last" | "sum" | "count" | "mean" | "distinct";
+    } | {
+        kind: "text";
+        text: string;
+    })[];
+} | {
+    key: string;
+})[];
+/**
+ * The fields a view shows: the domain's plus its formula columns (where the domain takes formulas),
+ * each number field in the format the view picked for it (`formats`).
+ */
+export declare function withViewFields<T>(domain: ViewDomain<T>, c: CustomViewConfig): ViewDomain<T>;
+/** Whether group and Total rows show a value for the field. */
+export declare const rollsUp: <T>(f: ViewField<T>) => boolean;
+/** A number field's Total pick as Edit view shows it: the view's, else the field's own. */
+export declare function totalAggOf<T>(f: ViewField<T>): ViewTotalAgg | 'own';
+export declare const pick: <T>(fields: ViewField<T>[], keys: string[]) => ViewField<T>[];
+/** A field the filter box can offer: one marked filterable, or any number field. */
+export declare const canFilter: <T>(f: ViewField<T>) => boolean;
+/** The fields a view's filter box offers: the ones it lists, else every field marked filterable. */
+export declare const filterFieldsOf: <T>(fields: ViewField<T>[], keys: string[]) => ViewField<T>[];
+/** A view's filters with `tokens` as the ones it opens with, offering every field they use. */
+export declare function withSavedFilters<T>(fields: ViewField<T>[], filters: CustomViewConfig['filters'], tokens: CustomViewConfig['filters']['default']): CustomViewConfig['filters'];
+export declare const label: (v: ViewCellValue) => string;
+/**
+ * Values over the shown rows: plain fields as read, share fields and formula columns worked out
+ * against the row's group (every shown row when not grouped) and every shown row.
+ */
+export declare function computedOf<T>(domain: ViewDomain<T>, rows: T[], groupBy: ViewField<T> | null): {
+    value: (f: ViewField<T>, r: T) => ViewCellValue;
+    roll: (f: ViewField<T>, rs: T[]) => ViewCellValue;
+};
+/**
+ * Each formula column that is blank on some of the rows, and why (a blank
+ * column said nothing): `blank on 24 of 24 rows: dew_point_f is empty`. The editor shows it under
+ * the formula, and the assistant reads it after each card move.
+ */
+export declare function formulaBlanks<T>(domain: ViewDomain<T>, rows: T[]): Map<string, string>;
+export declare const num: (v: ViewCellValue) => number;
+/** A field's group id: its own, else the domain's first group ('' when the domain has none). */
+export declare const groupOf: <T>(domain: ViewDomain<T>, f: ViewField<T>) => string;
+/**
+ * A field's name in formulas: the one it was made with (a join's
+ * `symbol.price`, a frame's `frame.<frame>.<column>`, a linked domain's `tax_lots.count`), a
+ * formula's bare key, else `<domain>.<key>` for the domain's own.
+ */
+export declare const fieldName: <T>(domain: ViewDomain<T>, f: ViewField<T>) => string;
+/** Each field by its name in formulas. */
+export declare const nameIndex: <T>(domain: ViewDomain<T>) => Map<string, ViewField<T>>;