@columenlabs/lumen-ui 0.0.0-stage → 0.1.0

package/dist/floating-head.js

@@ -0,0 +1,57 @@
+// A table that scrolls sideways in its own box (a card narrower than the page, or a view outside
+// a LumenLayout) can't pin its header with sticky: CSS makes any sideways scroller a scroller up and
+// down too, so sticky pins to that box, which never scrolls up and down. This slides the header
+// down with the page's scroller instead, under the page's sticky tabs (--pin-top), until the
+// table's bottom ("table headers are not sticky like they were").
+import { useEffect } from 'react';
+/** The nearest ancestor that scrolls up and down; null for the window. A sideways scroller around
+ *  the table (overflow-x makes overflow-y auto too) whose rows all fit is passed over: taking it
+ *  slid the header over the first row (the Tune card, 2026-10-15). */
+function scrollParentOf(el) {
+    for (let e = el.parentElement; e; e = e.parentElement) {
+        const y = getComputedStyle(e).overflowY;
+        if ((y === 'auto' || y === 'scroll') && e.scrollHeight > e.clientHeight)
+            return e;
+    }
+    return null;
+}
+export function useFloatingHead(box, on) {
+    useEffect(() => {
+        const el = box.current;
+        if (!on || !el)
+            return;
+        const scroller = scrollParentOf(el);
+        const target = scroller ?? window;
+        let frame = 0;
+        const place = () => {
+            frame = 0;
+            const head = el.querySelector(':scope table > thead');
+            const table = head?.parentElement;
+            if (!head || !table)
+                return;
+            const top = scroller ? scroller.getBoundingClientRect().top : 0;
+            // The scroller's own --pin-top: the table's box sets its own to 0 for its sticky cells.
+            const pin = Number.parseFloat(getComputedStyle(scroller ?? document.documentElement).getPropertyValue('--pin-top')) || 0;
+            const rect = table.getBoundingClientRect();
+            const y = Math.max(0, Math.min(top + pin - rect.top, rect.height - head.offsetHeight));
+            head.style.position = 'relative';
+            head.style.zIndex = '20';
+            head.style.transform = y > 0 ? `translateY(${y}px)` : '';
+        };
+        const queue = () => {
+            if (!frame)
+                frame = requestAnimationFrame(place);
+        };
+        place();
+        target.addEventListener('scroll', queue, { passive: true });
+        const seen = new ResizeObserver(queue);
+        seen.observe(el);
+        if (scroller)
+            seen.observe(scroller);
+        return () => {
+            target.removeEventListener('scroll', queue);
+            seen.disconnect();
+            cancelAnimationFrame(frame);
+        };
+    }, [box, on]);
+}

package/dist/fold.d.ts

@@ -0,0 +1,16 @@
+/** Whether the header `key` is folded, and a setter that remembers it. */
+export declare function useFolded(key: string): [boolean, (folded: boolean) => void];
+/** Every folded key at once, for headers drawn in a loop (a map's groups), and the setter. */
+export declare function useFolds(): [Set<string>, (key: string, folded: boolean) => void];
+/** The page's route (`/market/$symbol`), so a fold on one page holds for all its params. */
+export declare function usePageKey(): string;
+/**
+ * The chevron after a foldable header's name, always shown: it alone folds the header
+ *, so a click elsewhere on a header never folds it.
+ */
+export declare function FoldChevron({ folded, label, onToggle, className, }: {
+    folded: boolean;
+    label: string;
+    onToggle: () => void;
+    className?: string;
+}): import("react").JSX.Element;

package/dist/fold.js

@@ -0,0 +1,70 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// Folded section headers (option B): a header someone folds stays folded in
+// their browser. Sidebar sections fold across the app; cards and the groups inside them fold per
+// page (the route, so every symbol page shares one choice). One localStorage list per app host;
+// nothing is stored server-side, and a browser that refuses storage simply starts everything open.
+import { useRouterState } from '@tanstack/react-router';
+import { ChevronRightIcon } from 'lucide-react';
+import { useCallback, useSyncExternalStore } from 'react';
+import { cn } from './lib/utils.js';
+import { Button } from './ui/button.js';
+const KEY = 'edgeshell:folded';
+const listeners = new Set();
+let cache = null;
+function read() {
+    if (cache)
+        return cache;
+    try {
+        const raw = JSON.parse(localStorage.getItem(KEY) ?? '[]');
+        cache = new Set(Array.isArray(raw) ? raw.filter((k) => typeof k === 'string') : []);
+    }
+    catch {
+        cache = new Set();
+    }
+    return cache;
+}
+function write(key, folded) {
+    const next = new Set(read());
+    if (folded)
+        next.add(key);
+    else
+        next.delete(key);
+    cache = next;
+    try {
+        localStorage.setItem(KEY, JSON.stringify([...next]));
+    }
+    catch {
+        // Storage refused (private window, blocked site data): the fold still holds until reload.
+    }
+    for (const l of listeners)
+        l();
+}
+const subscribe = (l) => {
+    listeners.add(l);
+    return () => listeners.delete(l);
+};
+/** Whether the header `key` is folded, and a setter that remembers it. */
+export function useFolded(key) {
+    const folded = useSyncExternalStore(subscribe, () => read().has(key), () => false);
+    const set = useCallback((f) => write(key, f), [key]);
+    return [folded, set];
+}
+/** Every folded key at once, for headers drawn in a loop (a map's groups), and the setter. */
+export function useFolds() {
+    const folds = useSyncExternalStore(subscribe, read, () => EMPTY);
+    return [folds, write];
+}
+const EMPTY = new Set();
+/** The page's route (`/market/$symbol`), so a fold on one page holds for all its params. */
+export function usePageKey() {
+    return useRouterState({
+        select: (s) => String(s.matches.at(-1)?.routeId ?? s.location.pathname),
+    });
+}
+/**
+ * The chevron after a foldable header's name, always shown: it alone folds the header
+ *, so a click elsewhere on a header never folds it.
+ */
+export function FoldChevron({ folded, label, onToggle, className, }) {
+    return (_jsx(Button, { variant: "ghost", size: "icon-xs", "aria-expanded": !folded, "aria-label": `${folded ? 'Expand' : 'Collapse'} ${label}`, onClick: onToggle, className: cn('shrink-0 text-muted-foreground', className), children: _jsx(ChevronRightIcon, { className: cn('transition-transform', !folded && 'rotate-90') }) }));
+}

package/dist/form-issues.d.ts

@@ -0,0 +1,32 @@
+import { type ComponentType } from 'react';
+export interface FormIssue {
+    /** Where it is, in the form's words: `Formula value`, `Name`. */
+    where: string;
+    /** What to fix: `Unknown field shares_nonret`. */
+    message: string;
+    /** The DOM id of the field to take the person to. */
+    target?: string;
+    /** Opens what hides the field (a section, a tab, a sub-editor) before the jump. */
+    reveal?: () => void;
+}
+/** Opens what hides an issue, then scrolls to its field, focuses it and flashes it once. */
+export declare function goToIssue(issue: FormIssue): void;
+/**
+ * Save, and before it, while anything needs fixing, a chip with the count that lists each issue.
+ * Save stays tappable then and takes the person to the first issue instead of saving.
+ */
+export declare function SaveButton({ issues, onSave, label, icon: Icon, busy, disabled, type, className, }: {
+    issues: FormIssue[];
+    onSave?: () => void;
+    label?: string;
+    icon?: ComponentType<{
+        className?: string;
+    }> | null;
+    /** Saving now: Save waits. */
+    busy?: boolean;
+    /** Nothing to save (no change): Save is greyed and needs no reason. */
+    disabled?: boolean;
+    /** `submit` inside a form: the form's own submit runs only when there are no issues. */
+    type?: 'button' | 'submit';
+    className?: string;
+}): import("react").JSX.Element;

package/dist/form-issues.js

@@ -0,0 +1,60 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+// Save with issues: a Save that cannot go yet says why. Beside it a chip
+// counts what needs fixing and lists it; Save, and each line of the list, takes the person to the
+// issue: the editor opens its section or tab (`reveal`), then the field scrolls into view, takes
+// the cursor and flashes red once. Nothing saves while an issue stands. Every editor and form in
+// the suite uses this in place of a silent disabled Save.
+import { CheckIcon, TriangleAlertIcon } from 'lucide-react';
+import { useState } from 'react';
+import { cn } from './lib/utils.js';
+import { Button } from './ui/button.js';
+import { Popover, PopoverContent, PopoverTrigger } from './ui/popover.js';
+/** Opens what hides an issue, then scrolls to its field, focuses it and flashes it once. */
+export function goToIssue(issue) {
+    issue.reveal?.();
+    if (!issue.target)
+        return;
+    const id = issue.target;
+    // The field may mount only once its section opens: look for it for up to a second.
+    let tries = 0;
+    const find = () => {
+        const el = document.getElementById(id);
+        if (!el) {
+            if (++tries < 20)
+                setTimeout(find, 50);
+            return;
+        }
+        el.scrollIntoView({ block: 'center', behavior: 'smooth' });
+        el.focus({ preventScroll: true });
+        delete el.dataset.issueFlash;
+        // A frame between removing and setting restarts the animation on a second jump.
+        requestAnimationFrame(() => {
+            el.dataset.issueFlash = '';
+            setTimeout(() => delete el.dataset.issueFlash, 1200);
+        });
+    };
+    requestAnimationFrame(find);
+}
+/**
+ * Save, and before it, while anything needs fixing, a chip with the count that lists each issue.
+ * Save stays tappable then and takes the person to the first issue instead of saving.
+ */
+export function SaveButton({ issues, onSave, label = 'Save', icon: Icon = CheckIcon, busy = false, disabled = false, type = 'button', className, }) {
+    const [open, setOpen] = useState(false);
+    const blocked = issues.length > 0;
+    const first = issues[0];
+    const go = (issue) => {
+        setOpen(false);
+        goToIssue(issue);
+    };
+    return (_jsxs(_Fragment, { children: [blocked && (_jsxs(Popover, { open: open, onOpenChange: setOpen, children: [_jsx(PopoverTrigger, { asChild: true, children: _jsxs(Button, { type: "button", variant: "ghost", size: "sm", className: "text-destructive hover:text-destructive", children: [_jsx(TriangleAlertIcon, {}), issues.length, " to fix"] }) }), _jsxs(PopoverContent, { align: "end", className: "w-80 gap-1 p-1", children: [_jsxs("p", { className: "px-2 pt-1 text-xs text-muted-foreground", children: ["Fix ", issues.length === 1 ? 'this' : 'these', " to save. Tap one to go to it."] }), issues.map((issue, i) => (_jsxs(Button
+                            // biome-ignore lint/suspicious/noArrayIndexKey: two issues can share a place and message.
+                            , { type: "button", variant: "ghost", size: "sm", className: "h-auto w-full flex-col items-start gap-0 px-2 py-1.5 text-left font-normal whitespace-normal", onClick: () => go(issue), children: [_jsx("span", { className: "text-xs font-medium", children: issue.where }), _jsx("span", { className: "text-xs text-destructive", children: issue.message })] }, i)))] })] })), _jsxs(Button, { type: blocked ? 'button' : type, size: "sm", disabled: disabled || busy, "aria-disabled": blocked || undefined, className: cn(blocked && 'opacity-50', className), onClick: (e) => {
+                    if (first) {
+                        e.preventDefault();
+                        go(first);
+                    }
+                    else if (type === 'button')
+                        onSave?.();
+                }, children: [Icon && _jsx(Icon, {}), label] })] }));
+}

package/dist/formula-input.d.ts

@@ -0,0 +1,17 @@
+import type { LumenOption } from './lumen-selector.js';
+export declare function FormulaInput({ id, value, onChange, fields, invalid, placeholder, }: {
+    id?: string;
+    value: string;
+    onChange: (expr: string) => void;
+    /** What it can read: `value` the name, `label` what people call it, `group` its source. */
+    fields: LumenOption[];
+    invalid?: boolean;
+    placeholder?: string;
+}): import("react").JSX.Element;
+/**
+ * For an `unknown field X` issue: the field X most likely means, by label first (Price is
+ * price), then by the closest key or label.
+ */
+export declare function guessField(name: string, fields: LumenOption[]): LumenOption | null;
+/** `expr` with every whole name `from` swapped for `to` (never part of a longer name). */
+export declare const swapWord: (expr: string, from: string, to: string) => string;

package/dist/formula-input.js

@@ -0,0 +1,104 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { renameFormula } from '@columenlabs/lumen-ui-types/views';
+// Formula box with autocomplete: a formula reads fields by name, where they
+// come from and their key (`symbol.price`, `frame.earnings_next_week.eps`, a formula's bare key),
+// but people know fields by their labels (Price). Typing a word opens a LumenSelectorList under
+// the box that matches labels and names fuzzily (`prc` finds Price, `symbol.` lists the Symbol
+// fields); Tab or Enter puts the name in. It replaces the wall of key chips under the box.
+import { useLayoutEffect, useMemo, useRef, useState } from 'react';
+import { LumenSelectorList, fuzzyScore } from './lumen-selector.js';
+import { Textarea } from './ui/textarea.js';
+/** The roll-ups a formula can call, offered beside the fields. */
+const FUNCTIONS = [
+    {
+        value: 'group_sum("")',
+        label: 'group_sum',
+        detail: 'a field summed over its group',
+        group: 'Functions',
+    },
+    {
+        value: 'total_sum("")',
+        label: 'total_sum',
+        detail: 'a field summed over every row',
+        group: 'Functions',
+    },
+];
+/** The name the caret is in (dots included), from its start to the caret. */
+function wordAt(text, caret) {
+    const before = text.slice(0, caret);
+    const m = /[A-Za-z_][A-Za-z0-9_.]*$/.exec(before);
+    return m ? { start: caret - m[0].length, word: m[0] } : { start: caret, word: '' };
+}
+/** Does the name at `start` run on past the caret? Its whole length, for replacing it. */
+function wordEnd(text, caret) {
+    const m = /^[A-Za-z0-9_.]*/.exec(text.slice(caret));
+    return caret + (m?.[0].length ?? 0);
+}
+export function FormulaInput({ id, value, onChange, fields, invalid, placeholder, }) {
+    const box = useRef(null);
+    const list = useRef(null);
+    const [caret, setCaret] = useState(null);
+    const [closedAt, setClosedAt] = useState(null);
+    const moveTo = useRef(null);
+    const options = useMemo(() => [...fields.map((f) => ({ ...f, detail: f.value })), ...FUNCTIONS], [fields]);
+    const { start, word } = caret === null ? { start: 0, word: '' } : wordAt(value, caret);
+    const known = options.some((o) => o.value === word);
+    const open = caret !== null && word.length > 0 && !known && closedAt !== `${start}:${word}`;
+    useLayoutEffect(() => {
+        if (moveTo.current === null || !box.current)
+            return;
+        box.current.setSelectionRange(moveTo.current, moveTo.current);
+        setCaret(moveTo.current);
+        moveTo.current = null;
+    });
+    const pick = (o) => {
+        if (caret === null)
+            return;
+        const end = wordEnd(value, caret);
+        const fn = o.value.endsWith('("")');
+        const next = value.slice(0, start) + o.value + value.slice(end);
+        // A function's caret goes between its quotes, ready for the field it sums.
+        moveTo.current = start + (fn ? o.value.length - 2 : o.value.length);
+        onChange(next);
+    };
+    const track = () => setCaret(box.current?.selectionStart ?? null);
+    return (_jsxs("div", { className: "relative", children: [_jsx(Textarea, { ref: box, id: id, rows: 2, "aria-invalid": invalid || undefined, "aria-autocomplete": "list", className: "min-h-16 font-mono text-xs", placeholder: placeholder, value: value, spellCheck: false, onChange: (e) => {
+                    onChange(e.target.value);
+                    setCaret(e.target.selectionStart);
+                }, onKeyDown: (e) => {
+                    if (open && list.current?.key(e))
+                        return;
+                }, onKeyUp: (e) => {
+                    if (!['ArrowUp', 'ArrowDown', 'Enter', 'Tab', 'Escape'].includes(e.key))
+                        track();
+                }, onClick: track, onFocus: track, onBlur: () => setCaret(null) }), open && (_jsx(LumenSelectorList, { fuzzy: true, options: options, query: word, label: "Fields", handle: list, onPick: pick, onClose: () => setClosedAt(`${start}:${word}`), empty: `No field matches ${word}`, className: "absolute top-full z-30 mt-1 w-full max-w-md" }))] }));
+}
+/**
+ * For an `unknown field X` issue: the field X most likely means, by label first (Price is
+ * price), then by the closest key or label.
+ */
+export function guessField(name, fields) {
+    const n = name.toLowerCase();
+    // A name's field part: `price` (a formula from before names) or `holding.price` is `holdings.price`.
+    const part = n.slice(n.lastIndexOf('.') + 1);
+    const tail = (v) => v.toLowerCase().slice(v.lastIndexOf('.') + 1);
+    return (fields.find((f) => f.label.toLowerCase() === n) ??
+        fields.find((f) => f.value.toLowerCase() === n) ??
+        fields.find((f) => tail(f.value) === part) ??
+        fields.find((f) => f.label.toLowerCase().replace(/[^a-z0-9]+/g, '_') === part) ??
+        closest(part, fields));
+}
+function closest(n, fields) {
+    let best = null;
+    let top = 0;
+    for (const f of fields) {
+        const key = f.value.slice(f.value.lastIndexOf('.') + 1);
+        const v = Math.max(fuzzyScore(n, f.label) ?? 0, fuzzyScore(n, key) ?? 0);
+        if (v > top)
+            [best, top] = [f, v];
+    }
+    // Only a match on most of its letters in order, never a stray one.
+    return top >= n.length * 2 ? best : null;
+}
+/** `expr` with every whole name `from` swapped for `to` (never part of a longer name). */
+export const swapWord = (expr, from, to) => renameFormula(expr, (n) => (n === from ? to : n));

package/dist/frame-script.d.ts

@@ -0,0 +1,7 @@
+export declare function FrameScriptDialog({ api, frame, name, open, onOpenChange, }: {
+    api: string;
+    frame: string;
+    name: string;
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+}): import("react").JSX.Element;

package/dist/frame-script.js

@@ -0,0 +1,103 @@
+import { jsxs as _jsxs, jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { PlayIcon, RotateCcwIcon, WrapTextIcon } from 'lucide-react';
+import { useEffect, useMemo, useState } from 'react';
+import { apiJson } from './api-fetch.js';
+import { useAssistantName } from './assistant-context.js';
+// A frame's Script editor: the one script that makes an assistant's table (a call as
+// JSON, SQL, or JavaScript), as code the person reads and edits, in a dialog off the card's signal
+// dot or ⋯ menu. Run and save runs the edited script once as the person, with the read tools the
+// assistant may use; it becomes the frame's script only when it works, and a failure shows here.
+import { LumenCodeEditor } from './lumen-code-editor.js';
+import { lumenToast } from './lumen-toast.js';
+import { IconButton } from './page.js';
+import { Alert, AlertDescription, AlertTitle } from './ui/alert.js';
+import { Badge } from './ui/badge.js';
+import { Button } from './ui/button.js';
+import { Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, } from './ui/dialog.js';
+import { Skeleton } from './ui/skeleton.js';
+import { Spinner } from './ui/spinner.js';
+import { WORKSPACES_KEY, frameKey } from './workspace-keys.js';
+const json = (url, init) => apiJson(url, init, 'workspaces');
+/** The script as the text the editor shows, and its language. */
+function scriptText(s) {
+    if (s.kind === 'script')
+        return { text: s.code, lang: 'js' };
+    if (s.kind === 'sql')
+        return { text: s.query, lang: 'sql' };
+    return { text: JSON.stringify({ fn: s.fn, args: s.args }, null, 2), lang: 'json' };
+}
+/** The edited text back as a script; a call that is not JSON says where. */
+function parseScript(was, text) {
+    if (was.kind === 'script')
+        return { kind: 'script', code: text };
+    if (was.kind === 'sql')
+        return { kind: 'sql', query: text };
+    let v;
+    try {
+        v = JSON.parse(text);
+    }
+    catch (e) {
+        throw new Error(`The call is not valid JSON: ${e.message}`);
+    }
+    const o = (v ?? {});
+    return {
+        kind: 'call',
+        fn: String(o.fn ?? ''),
+        args: (o.args ?? {}),
+    };
+}
+export function FrameScriptDialog({ api, frame, name, open, onOpenChange, }) {
+    const qc = useQueryClient();
+    const assistant = useAssistantName();
+    const read = useQuery({
+        queryKey: [...frameKey(api, frame), 'script'],
+        queryFn: () => json(`${api}/frames/${frame}/script`),
+        enabled: open,
+        staleTime: 0,
+    });
+    const script = read.data?.script ?? null;
+    const [text, setText] = useState('');
+    // Unwrapped by default: long lines scroll sideways like a code editor.
+    const [wrap, setWrap] = useState(false);
+    const [error, setError] = useState(null);
+    const original = useMemo(() => (script ? scriptText(script).text : ''), [script]);
+    useEffect(() => {
+        if (!open)
+            return;
+        setText(original);
+        setError(null);
+    }, [open, original]);
+    const save = useMutation({
+        mutationFn: (next) => json(`${api}/frames/${frame}/script`, {
+            method: 'PUT',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ script: next }),
+        }),
+        onSuccess: (data) => {
+            qc.setQueryData(frameKey(api, frame), data);
+            void qc.invalidateQueries({ queryKey: [...frameKey(api, frame), 'script'] });
+            void qc.invalidateQueries({ queryKey: [...WORKSPACES_KEY, api, 'ws'] });
+            lumenToast.success(`Ran your script: ${data.meta.rows.toLocaleString('en-US')} rows, saved`);
+            onOpenChange(false);
+        },
+        onError: (e) => setError(e.message),
+    });
+    const lang = script ? scriptText(script).lang : undefined;
+    const changed = text !== original;
+    const run = () => {
+        if (!script)
+            return;
+        setError(null);
+        try {
+            save.mutate(parseScript(script, text));
+        }
+        catch (e) {
+            setError(e.message);
+        }
+    };
+    return (_jsx(Dialog, { open: open, onOpenChange: onOpenChange, children: _jsxs(DialogContent, { className: "flex h-[min(44rem,calc(100dvh-2rem))] flex-col sm:max-w-4xl", children: [_jsxs(DialogHeader, { children: [_jsxs(DialogTitle, { children: ["Script \u00B7 ", name] }), _jsxs(DialogDescription, { children: ["What ", assistant, " runs to make these rows. Saved only if it runs."] })] }), read.isPending ? (_jsx(Skeleton, { className: "min-h-0 flex-1" })) : read.error ? (_jsxs(Alert, { variant: "destructive", children: [_jsx(AlertTitle, { children: "Couldn't read the script" }), _jsx(AlertDescription, { children: read.error.message })] })) : !script ? (_jsxs(Alert, { children: [_jsx(AlertTitle, { children: "No script" }), _jsxs(AlertDescription, { children: [assistant, " wrote these rows once: nothing runs to make them."] })] })) : (_jsxs(_Fragment, { children: [_jsxs("div", { className: "flex items-center justify-end gap-1", children: [lang && (_jsx(Badge, { variant: "secondary", className: "font-mono", children: lang })), _jsx(IconButton, { icon: WrapTextIcon, label: wrap ? 'Stop wrapping lines' : 'Wrap long lines', pressed: wrap, onClick: () => setWrap(!wrap) })] }), _jsx(LumenCodeEditor, { className: "flex-1", value: text, lang: lang, wrap: wrap, onChange: setText }), error && (_jsxs(Alert, { variant: "destructive", className: "max-h-32 overflow-y-auto", children: [_jsx(AlertTitle, { children: "Didn't save" }), _jsx(AlertDescription, { className: "break-words font-mono text-xs", children: error })] }))] })), _jsxs(DialogFooter, { children: [_jsx(IconButton, { icon: RotateCcwIcon, label: "Undo my changes", disabled: !changed || save.isPending, onClick: () => {
+                                setText(original);
+                                setError(null);
+                            } }), _jsxs(Button, { disabled: !script || save.isPending, onClick: run, children: [save.isPending ? _jsx(Spinner, {}) : _jsx(PlayIcon, {}), " Run and save"] })] })] }) }));
+}

package/dist/freshness.d.ts

@@ -0,0 +1,24 @@
+import { type ViewDomain, type ViewField } from './view-model.js';
+export type Freshness = 'live' | 'calc' | 'asof';
+export declare const FRESHNESS: Record<Freshness, {
+    label: string;
+    about: string;
+}>;
+/** How a field updates: live, live calc, as of, or null for fixed. */
+export declare function freshnessOf<T>(domain: ViewDomain<T>, f: ViewField<T>, seen?: Set<string>): Freshness | null;
+/** The live fields a Live calc field reads, by label, for its tooltip (`from Price`). */
+export declare function liveInputs<T>(domain: ViewDomain<T>, f: ViewField<T>): string[];
+/** The tooltip line under a header's path: `Live: moves with the market while it trades`. */
+export declare function freshnessLine<T>(domain: ViewDomain<T>, f: ViewField<T>): string | null;
+/** The mark itself, drawn: a green dot for Live, a calculator for Live calc, a clock for As of. */
+export declare function FreshnessIcon({ kind, className }: {
+    kind: Freshness;
+    className?: string;
+}): import("react").JSX.Element;
+/** The mark beside a header's name; nothing for a fixed field. */
+export declare function FreshnessMark<T>({ domain, field, }: {
+    domain: ViewDomain<T>;
+    field: ViewField<T>;
+}): import("react").JSX.Element | null;
+/** The marks the shown columns carry, in order live, live calc, as of. */
+export declare function marksOf<T>(domain: ViewDomain<T>, columns: ViewField<T>[]): Freshness[];

package/dist/freshness.js

@@ -0,0 +1,99 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Freshness marks:
+// a column's colour says where it comes from, and a small mark beside its name says how it
+// updates: a green dot Live (moves with the market: a quote), a calculator Live calc (worked out
+// from a live field: Value, Unrealized, a formula over Price; , #861), ◷ As of (a daily or snapshot value: a close, a fact,
+// the assistant frame's column) and nothing for a fixed value (Qty, Cost). Declared once on each field
+// (`updates`, `from`); a formula's mark comes from the fields its expression reads.
+import { formulaReads } from '@columenlabs/lumen-ui-types/views';
+import { CalculatorIcon } from 'lucide-react';
+import { FORMULAS_GROUP, groupOf, nameIndex } from './view-model.js';
+export const FRESHNESS = {
+    live: { label: 'Live', about: 'moves with the market while it trades' },
+    calc: { label: 'Live calc', about: 'worked out from a live field' },
+    asof: { label: 'As of', about: 'a daily or snapshot value' },
+};
+/** The field keys a field is made from: its `from`, a share's field, the names a formula reads. */
+function inputsOf(domain, f) {
+    const out = new Set(f.from ?? []);
+    if (f.share)
+        out.add(f.share.of);
+    if (groupOf(domain, f) === FORMULAS_GROUP && f.formula) {
+        const byName = nameIndex(domain);
+        for (const n of formulaReads(f.formula)) {
+            const k = byName.get(n)?.key;
+            if (k && k !== f.key)
+                out.add(k);
+        }
+    }
+    return [...out];
+}
+/** How a field updates: live, live calc, as of, or null for fixed. */
+export function freshnessOf(domain, f, seen = new Set()) {
+    if (f.updates === 'live')
+        return 'live';
+    if (f.updates === 'calc')
+        return 'calc';
+    seen.add(f.key);
+    let asof = f.updates === 'asof';
+    for (const k of inputsOf(domain, f)) {
+        if (seen.has(k))
+            continue;
+        const g = domain.fields.find((x) => x.key === k);
+        if (!g)
+            continue;
+        const r = freshnessOf(domain, g, seen);
+        if (r === 'live' || r === 'calc')
+            return 'calc';
+        if (r === 'asof')
+            asof = true;
+    }
+    return asof ? 'asof' : null;
+}
+/** The live fields a Live calc field reads, by label, for its tooltip (`from Price`). */
+export function liveInputs(domain, f) {
+    return inputsOf(domain, f)
+        .map((k) => domain.fields.find((x) => x.key === k))
+        .filter((g) => {
+        if (!g)
+            return false;
+        const r = freshnessOf(domain, g, new Set([f.key]));
+        return r === 'live' || r === 'calc';
+    })
+        .map((g) => g.label);
+}
+/** The tooltip line under a header's path: `Live: moves with the market while it trades`. */
+export function freshnessLine(domain, f) {
+    const r = freshnessOf(domain, f);
+    if (!r)
+        return null;
+    const m = FRESHNESS[r];
+    if (r === 'calc') {
+        const from = liveInputs(domain, f);
+        return `${m.label}: worked out from ${from.length ? from.join(', ') : 'a live field'}`;
+    }
+    return `${m.label}: ${m.about}`;
+}
+/** The mark itself, drawn: a green dot for Live, a calculator for Live calc, a clock for As of. */
+export function FreshnessIcon({ kind, className }) {
+    const base = `inline-block shrink-0 align-[-0.05em] ${className ?? ''}`;
+    const cls = `${base} size-[0.62rem]`;
+    const label = FRESHNESS[kind].label;
+    if (kind === 'calc')
+        return (_jsx(CalculatorIcon, { className: `${base} size-3`, strokeWidth: 2.4, role: "img", "aria-label": label }));
+    if (kind === 'live')
+        return (_jsx("svg", { viewBox: "0 0 12 12", className: `${cls} text-gain`, role: "img", "aria-label": label, children: _jsx("circle", { cx: "6", cy: "6", r: "3.6", fill: "currentColor" }) }));
+    return (_jsxs("svg", { viewBox: "0 0 12 12", className: cls, role: "img", "aria-label": label, children: [_jsx("circle", { cx: "6", cy: "6", r: "4.6", fill: "none", stroke: "currentColor", strokeWidth: "1.4" }), _jsx("path", { d: "M6 3.4V6l1.8 1.2", fill: "none", stroke: "currentColor", strokeWidth: "1.3", strokeLinecap: "round" })] }));
+}
+/** The mark beside a header's name; nothing for a fixed field. */
+export function FreshnessMark({ domain, field, }) {
+    const r = freshnessOf(domain, field);
+    if (!r)
+        return null;
+    return (_jsx("span", { className: "mr-1 inline-flex opacity-80", children: _jsx(FreshnessIcon, { kind: r }) }));
+}
+/** The marks the shown columns carry, in order live, live calc, as of. */
+export function marksOf(domain, columns) {
+    const got = new Set(columns.map((c) => freshnessOf(domain, c)));
+    return ['live', 'calc', 'asof'].filter((r) => got.has(r));
+}

package/dist/group-button.d.ts

@@ -0,0 +1,33 @@
+import type { CustomViewConfig } from '@columenlabs/lumen-ui-types/views';
+import { type ViewDomain, type ViewField, type ViewSubgroup } from './view-model.js';
+export declare const GROUP_NONE = "_none";
+export declare const GROUP_PIVOT = "_pivot";
+/** A view's grouping for the visit: by a field, as a pivot, and what each row opens. */
+export declare function useGroup<T>(domain: ViewDomain<T>, config: CustomViewConfig): {
+    groupField: ViewField<T> | null;
+    pivot: boolean;
+    sub: string | null;
+    button: import("react").JSX.Element | null;
+    held: {
+        group: string | null;
+        pivot: boolean;
+        subgroup: string | null;
+    };
+    reset: () => void;
+};
+/**
+ * The Group button: says what is on ("Account › Tax lots") and opens two
+ * pickers, Group rows by (a field, or Pivot) and Each row opens (the domain's sub-groups), each
+ * with None.
+ */
+export declare function GroupButton<T>({ groupable, pivot, mode, onMode, subgroups, subgroup, onSubgroup, opensLabel, }: {
+    groupable: ViewField<T>[];
+    pivot: boolean;
+    mode: string;
+    onMode: (mode: string) => void;
+    subgroups: ViewSubgroup<T>[];
+    subgroup: string | null;
+    onSubgroup: (key: string | null) => void;
+    /** The sub-group picker's name (`subgroupLabel`). */
+    opensLabel?: string;
+}): import("react").JSX.Element;