@columenlabs/lumen-ui 0.0.0-stage → 0.2.1

package/dist/lumen-links.d.ts

@@ -0,0 +1,96 @@
+import type { JoinKey } from '@columenlabs/lumen-ui-types/domains';
+import { type ViewLinkColor } from '@columenlabs/lumen-ui-types/views';
+import { type ReactNode } from 'react';
+import type { FilterField, FilterToken } from './lumen-filter.js';
+export type LinkColor = ViewLinkColor;
+export declare const LINK_COLORS: readonly ["teal", "amber", "pink", "lime", "blue"];
+export declare const LINK_NAMES: Record<LinkColor, string>;
+/** The colour as CSS (a theme token). */
+export declare const linkVar: (c: LinkColor) => string;
+interface Links {
+    colorOf: (id: string) => LinkColor | null;
+    setColor: (id: string, color: LinkColor | null) => void;
+    /** A card's shared chips (all of its filter's chips and its tapped row, while it has a colour). */
+    publish: (id: string, tokens: FilterToken[]) => void;
+    /** The linked chips of every other card of this card's colour. */
+    follows: (id: string) => FilterToken[];
+}
+export declare const useLinks: () => Links | null;
+/**
+ * Keeps the page's card colours and linked chips. `initial` are the saved colours by card id;
+ * `kept` names the page and its code-built cards, whose picks this browser remembers.
+ */
+export declare function useLinkState(saved: Record<string, LinkColor | null>, kept?: {
+    page: string;
+    ids: string[];
+}): {
+    links: Links;
+    colors: Record<string, "amber" | "blue" | "lime" | "pink" | "teal" | null>;
+};
+export declare const useCardId: () => string | null;
+export declare function CardIdProvider({ id, children }: {
+    id: string;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function LinksProvider({ links, children }: {
+    links: Links;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** A filter box's link from the card it sits in, when its card passes none (*  the square is built into every card). Its linked chips are published as that card's. */
+export declare function useAutoFilterLink(tokens: FilterToken[], given: FilterLink | null | undefined): FilterLink | undefined;
+/** The fields that stand for a key on any domain, so a chip on one is followed by that key. */
+export declare const KEY_FIELDS: Record<JoinKey, string[]>;
+/** A coloured card's chips as its group gets them: its colour, and the key a key field stands for. */
+export declare function shared(tokens: FilterToken[], color: LinkColor | null): FilterToken[];
+/** Publishes a coloured card's chips while it shows, and takes them back when it goes. */
+export declare function usePublishLinks(id: string, tokens: FilterToken[]): void;
+/** A domain's keys as filter fields (`@symbol`, `@account`), so a followed chip reads by key. */
+export declare function keyFilterFields<T>(keys: Partial<Record<JoinKey, (row: T) => string | string[] | null>> | undefined): FilterField<T>[];
+/**
+ * The followed chips a card can read: those on a field it has, then those on a key it carries
+ * (read on `@<key>`, see `keyFilterFields`). A chip it can read neither way is skipped.
+ */
+export declare function followedBy<T>(tokens: FilterToken[], fields: FilterField<T>[], keys?: Partial<Record<JoinKey, unknown>>): FilterToken[];
+/** What a card follows, as its title says it: `IRA, Roth`. */
+export declare function followsText(tokens: FilterToken[]): string;
+/** The square itself: filled in its colour, or an outline for none. */
+export declare function LinkDot({ color, className }: {
+    color: LinkColor | null;
+    className?: string;
+}): import("react").JSX.Element;
+/** A card's square: a tap opens the colours and None; a pick applies at once. */
+export declare function LinkPicker({ color, onPick, label, className, }: {
+    color: LinkColor | null;
+    onPick: (c: LinkColor | null) => void;
+    label: string;
+    className?: string;
+}): import("react").JSX.Element;
+/** What a filter box needs to show its chips' squares. */
+export interface FilterLink {
+    /** Its card's colour; a chip square carries it. */
+    color: LinkColor | null;
+    /** Picks the card's colour (a chip square on a card with none asks for one first). */
+    onPick: (c: LinkColor | null) => void;
+}
+/**
+ * Row-tap filtering (keyed): in a coloured card a row tap picks the
+ * row's value as a temporary chip of the card's colour (published with its other chips); a second
+ * tap on it, or the card losing its colour, lets go. The value is the domain's `rowLink` field, else
+ * its first key (symbol, then account), so every domain with a key links rows (a basket's orders,
+ * paper and live). `onTap` is undefined where it does not apply, so the row opens as usual.
+ */
+export declare function useRowPick<T>(domain: {
+    rowLink?: string;
+    fields: {
+        key: string;
+        value: (row: T) => unknown;
+    }[];
+    keys?: Partial<Record<JoinKey, (row: T) => string | string[] | null>>;
+}, color: LinkColor | null, 
+/** The value tapped until a tap changes it (a page that opens on one row). */
+initial?: string): {
+    token: FilterToken[];
+    onTap: ((row: T) => void) | undefined;
+    tapped: ((row: T) => boolean) | undefined;
+};
+export {};

package/dist/lumen-links.js

@@ -0,0 +1,213 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { viewLinkColors } from '@columenlabs/lumen-ui-types/views';
+import { LinkIcon } from 'lucide-react';
+import { createContext, useCallback, useContext, useEffect, useMemo, useState, } from 'react';
+import { cn } from './lib/utils.js';
+import { Button } from './ui/button.js';
+import { Popover, PopoverContent, PopoverTrigger } from './ui/popover.js';
+export const LINK_COLORS = viewLinkColors;
+export const LINK_NAMES = {
+    teal: 'Teal',
+    amber: 'Amber',
+    pink: 'Pink',
+    lime: 'Lime',
+    blue: 'Blue',
+};
+/** The colour as CSS (a theme token). */
+export const linkVar = (c) => `var(--link-${c})`;
+const LinksContext = createContext(null);
+export const useLinks = () => useContext(LinksContext);
+// Code-built cards ("yes, save it"): their colour picks have no saved view to
+// live in, so each browser keeps them per page route, like folds. Nothing is stored server-side; a
+// browser that refuses storage keeps the picks for the visit only.
+const KEY = 'edgeshell:links';
+function readRemembered() {
+    try {
+        const raw = JSON.parse(localStorage.getItem(KEY) ?? '{}');
+        return raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : {};
+    }
+    catch {
+        return {};
+    }
+}
+function remember(page, id, color) {
+    const all = readRemembered();
+    all[page] = { ...all[page], [id]: color };
+    try {
+        localStorage.setItem(KEY, JSON.stringify(all));
+    }
+    catch {
+        // Storage refused: the pick still holds until reload.
+    }
+}
+const isColor = (c) => c === null || LINK_COLORS.includes(c);
+/**
+ * Keeps the page's card colours and linked chips. `initial` are the saved colours by card id;
+ * `kept` names the page and its code-built cards, whose picks this browser remembers.
+ */
+export function useLinkState(saved, kept) {
+    const page = kept?.page;
+    const ids = kept?.ids.join('\n') ?? '';
+    // biome-ignore lint/correctness/useExhaustiveDependencies: keyed on the saved colours and ids.
+    const initial = useMemo(() => {
+        if (!page)
+            return saved;
+        const mine = readRemembered()[page] ?? {};
+        const own = Object.entries(mine).filter(([id, c]) => ids.split('\n').includes(id) && isColor(c));
+        return { ...saved, ...Object.fromEntries(own) };
+    }, [JSON.stringify(saved), page, ids]);
+    const [colors, setColors] = useState(initial);
+    const [sources, setSources] = useState({});
+    // A saved layout that changes (another view, a save) starts from its colours again.
+    const key = JSON.stringify(initial);
+    // biome-ignore lint/correctness/useExhaustiveDependencies: keyed on the saved colours.
+    useEffect(() => setColors(initial), [key]);
+    // Stable, so a card's effects that publish never run again only because the page re-rendered.
+    const setColor = useCallback((id, color) => {
+        if (page && ids.split('\n').includes(id))
+            remember(page, id, color);
+        setColors((c) => ({ ...c, [id]: color }));
+    }, [page, ids]);
+    const publish = useCallback((id, tokens) => setSources((s) => JSON.stringify(s[id] ?? []) === JSON.stringify(tokens) ? s : { ...s, [id]: tokens }), []);
+    const links = useMemo(() => ({
+        colorOf: (id) => colors[id] ?? null,
+        setColor,
+        publish,
+        follows: (id) => {
+            const color = colors[id];
+            if (!color)
+                return [];
+            return Object.entries(sources).flatMap(([src, ts]) => src !== id && colors[src] === color ? ts : []);
+        },
+    }), [colors, sources, setColor, publish]);
+    return { links, colors };
+}
+/** The id of the card a part sits in, so a filter box in any card links without being told. */
+const CardIdContext = createContext(null);
+export const useCardId = () => useContext(CardIdContext);
+export function CardIdProvider({ id, children }) {
+    return _jsx(CardIdContext.Provider, { value: id, children: children });
+}
+export function LinksProvider({ links, children }) {
+    return _jsx(LinksContext.Provider, { value: links, children: children });
+}
+/** A filter box's link from the card it sits in, when its card passes none (*  the square is built into every card). Its linked chips are published as that card's. */
+export function useAutoFilterLink(tokens, given) {
+    const links = useLinks();
+    const id = useCardId();
+    // `null`: a box that never shares (a widget's own fixed filter in Edit widget).
+    const auto = given === undefined && !!links && !!id;
+    usePublishLinks(auto ? id : '', auto ? tokens : NONE);
+    if (given === null)
+        return undefined;
+    if (given || !auto || !links || !id)
+        return given;
+    return { color: links.colorOf(id), onPick: (c) => links.setColor(id, c) };
+}
+const NONE = [];
+/** The fields that stand for a key on any domain, so a chip on one is followed by that key. */
+export const KEY_FIELDS = {
+    symbol: ['symbol', 'underlying', 'ticker'],
+    account: ['account', 'account_id'],
+    contract: ['contract'],
+};
+const keyOfField = (key) => Object.keys(KEY_FIELDS).find((k) => KEY_FIELDS[k].includes(key));
+/** A coloured card's chips as its group gets them: its colour, and the key a key field stands for. */
+export function shared(tokens, color) {
+    if (!color)
+        return [];
+    return tokens.map((t) => {
+        const as = t.as ?? keyOfField(t.key);
+        return { ...t, link: color, ...(as ? { as } : {}) };
+    });
+}
+/** Publishes a coloured card's chips while it shows, and takes them back when it goes. */
+export function usePublishLinks(id, tokens) {
+    const links = useLinks();
+    const color = links?.colorOf(id) ?? null;
+    const linked = useMemo(() => shared(tokens, color), [color, tokens]);
+    const publish = links?.publish;
+    useEffect(() => publish?.(id, linked), [publish, id, linked]);
+    useEffect(() => () => publish?.(id, []), [publish, id]);
+}
+/** A domain's keys as filter fields (`@symbol`, `@account`), so a followed chip reads by key. */
+export function keyFilterFields(keys) {
+    return Object.entries(keys ?? {}).map(([k, read]) => ({
+        key: `@${k}`,
+        label: k === 'symbol' ? 'Symbol' : k === 'account' ? 'Account' : 'Option',
+        icon: LinkIcon,
+        values: (row) => {
+            const v = read(row);
+            return v === null ? [] : Array.isArray(v) ? v : [v];
+        },
+    }));
+}
+/**
+ * The followed chips a card can read: those on a field it has, then those on a key it carries
+ * (read on `@<key>`, see `keyFilterFields`). A chip it can read neither way is skipped.
+ */
+export function followedBy(tokens, fields, keys) {
+    return tokens.flatMap((t) => fields.some((f) => f.key === t.key)
+        ? [t]
+        : t.as && keys?.[t.as]
+            ? [{ ...t, key: `@${t.as}` }]
+            : []);
+}
+/** What a card follows, as its title says it: `IRA, Roth`. */
+export function followsText(tokens) {
+    return tokens
+        .map((t) => `${t.not ? 'not ' : ''}${t.op ? `${t.key} ${t.value.replace('..', '–')}` : (t.text ?? t.value)}`)
+        .join(', ');
+}
+/** The square itself: filled in its colour, or an outline for none. */
+export function LinkDot({ color, className }) {
+    return (_jsx("span", { "aria-hidden": true, className: cn('inline-block size-2.5 shrink-0 rounded-[3px]', !color && 'ring-[1.5px] ring-muted-foreground/60 ring-inset', className), style: color ? { background: linkVar(color) } : undefined }));
+}
+/** A card's square: a tap opens the colours and None; a pick applies at once. */
+export function LinkPicker({ color, onPick, label, className, }) {
+    const [open, setOpen] = useState(false);
+    const pick = (c) => {
+        onPick(c);
+        setOpen(false);
+    };
+    return (_jsxs(Popover, { open: open, onOpenChange: setOpen, children: [_jsx(PopoverTrigger, { asChild: true, children: _jsx(Button, { variant: "ghost", size: "icon-xs", className: cn('size-5 shrink-0', className), "aria-label": `${label} link colour: ${color ? LINK_NAMES[color] : 'None'}`, title: color ? `Linked: ${LINK_NAMES[color]}` : 'Link colour', children: _jsx(LinkDot, { color: color }) }) }), _jsxs(PopoverContent, { align: "start", className: "flex w-auto flex-col gap-2 p-2", children: [_jsx("p", { className: "text-xs text-muted-foreground", children: "Link colour" }), _jsxs("div", { className: "flex items-center gap-1", children: [LINK_COLORS.map((c) => (_jsx(Button, { variant: c === color ? 'secondary' : 'ghost', size: "icon-sm", "aria-label": LINK_NAMES[c], "aria-pressed": c === color, title: LINK_NAMES[c], onClick: () => pick(c), children: _jsx(LinkDot, { color: c, className: "size-3.5" }) }, c))), _jsx(Button, { variant: color === null ? 'secondary' : 'ghost', size: "sm", className: "h-8 px-2 text-xs", "aria-pressed": color === null, onClick: () => pick(null), children: "None" })] })] })] }));
+}
+/**
+ * Row-tap filtering (keyed): in a coloured card a row tap picks the
+ * row's value as a temporary chip of the card's colour (published with its other chips); a second
+ * tap on it, or the card losing its colour, lets go. The value is the domain's `rowLink` field, else
+ * its first key (symbol, then account), so every domain with a key links rows (a basket's orders,
+ * paper and live). `onTap` is undefined where it does not apply, so the row opens as usual.
+ */
+export function useRowPick(domain, color, 
+/** The value tapped until a tap changes it (a page that opens on one row). */
+initial) {
+    const field = domain.rowLink ? domain.fields.find((f) => f.key === domain.rowLink) : undefined;
+    const key = field ? undefined : ['symbol', 'account'].find((k) => domain.keys?.[k]);
+    const read = key ? domain.keys?.[key] : undefined;
+    // Until the first tap the page's own start holds; a tap, or the card losing its colour, ends it.
+    const [tap, setTap] = useState(null);
+    const on = !!((field || read) && color);
+    useEffect(() => {
+        if (!on)
+            setTap(null);
+    }, [on]);
+    const value = tap ? tap.value : (initial ?? null);
+    const keyOf = useCallback((row) => {
+        const v = field ? field.value(row) : read?.(row);
+        const one = Array.isArray(v) ? v[0] : v;
+        return one === null || one === undefined ? null : String(one);
+    }, [field, read]);
+    const token = useMemo(() => {
+        if (!on || !value)
+            return [];
+        if (field)
+            return [{ key: field.key, value, link: color ?? undefined }];
+        return key ? [{ key: `@${key}`, value, as: key, link: color ?? undefined }] : [];
+    }, [on, value, field, key, color]);
+    return {
+        token,
+        onTap: on ? (row) => setTap({ value: value === keyOf(row) ? null : keyOf(row) }) : undefined,
+        tapped: on && value ? (row) => keyOf(row) === value : undefined,
+    };
+}

package/dist/lumen-page-state.d.ts

@@ -0,0 +1,20 @@
+import type { UseQueryResult } from '@tanstack/react-query';
+import type { LucideIcon } from 'lucide-react';
+import type { Crumb } from './page.js';
+export declare function LumenPageState({ crumbs, title, icon, query, waiting, error, notFound, tabs, }: {
+    /** The crumbs before the page's own; the last one says …, Not found or Could not load. */
+    crumbs: Crumb[];
+    /** The placeholder card's name and icon, as the page's first card shows them. */
+    title: string;
+    icon: LucideIcon;
+    /** What the page waits on; none when the address itself is wrong. */
+    query?: Pick<UseQueryResult<unknown, Error>, 'data' | 'error' | 'isError' | 'isFetching' | 'isPending' | 'dataUpdatedAt' | 'refetch'>;
+    /** Something else the page needs is not known yet (whether the app has the assistant). */
+    waiting?: boolean;
+    /** A known reason the page cannot load, shown in place of Not found. */
+    error?: Error | null;
+    /** Said once the page is proven missing. */
+    notFound?: string;
+    /** The page has a tab row: its skeleton shows above the card while loading. */
+    tabs?: boolean;
+}): import("react").JSX.Element;

package/dist/lumen-page-state.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ApiError } from './api-fetch.js';
+import { LumenLayout } from './lumen-layout.js';
+import { useLumenLoad } from './lumen-source.js';
+import { Skeleton } from './ui/skeleton.js';
+export function LumenPageState({ crumbs, title, icon, query, waiting = false, error, notFound = 'Nothing here with this id. It may have been deleted.', tabs = false, }) {
+    const read = useLumenLoad(...(query ? [query] : []));
+    const failed = query?.isError ? query.error : null;
+    const loading = !error && (waiting || (!!query?.isPending && !failed));
+    const missing = !loading && !error && (!failed || (failed instanceof ApiError && failed.status === 404));
+    const load = loading
+        ? { ...read, loading: true, fetching: true, error: null }
+        : { ...read, loading: false, error: missing ? new Error(notFound) : (error ?? failed) };
+    return (_jsx(LumenLayout, { crumbs: [...crumbs, { label: loading ? '…' : missing ? 'Not found' : 'Could not load' }], intro: tabs && loading ? (_jsxs("div", { "aria-busy": "true", "aria-label": "Loading tabs", className: "flex gap-2", children: [_jsx(Skeleton, { className: "h-8 w-28" }), _jsx(Skeleton, { className: "h-8 w-24" }), _jsx(Skeleton, { className: "h-8 w-20" })] })) : undefined, cards: [{ id: 'page', link: false, title, icon, kind: 'table', load, children: null }] }));
+}

package/dist/lumen-selector.d.ts

@@ -0,0 +1,139 @@
+import { type ComponentType, type ReactNode, type Ref } from 'react';
+type Icon = ComponentType<{
+    className?: string;
+}>;
+export interface LumenOption<V extends string = string> {
+    value: V;
+    label: string;
+    /** Section heading; rows with the same group sit together, groups in first-seen order. */
+    group?: string;
+    /** Second column on the right: "Screeners", "34d", "Fidelity · IRA". */
+    detail?: string;
+    icon?: Icon;
+    /** Drawn in place of the label in the row and the trigger (a model's name with its badge). */
+    content?: ReactNode;
+    /** A second line under the label, in the list only: when to pick it (the
+     *  Widget picker). A row with one is taller. */
+    description?: string;
+    /** A small picture before the label, in the list only (a widget style's thumbnail). */
+    thumb?: ReactNode;
+    /** Extra words search matches. */
+    keywords?: string[];
+    /** Not pickable; a string says why (tooltip). */
+    disabled?: boolean | string;
+    /** Sits one step in, under the row before it (a workspace's tabs). */
+    indent?: boolean;
+    /** What the option stands for on screen, lit while hovered: `card:<id>` or an app path. */
+    target?: string;
+    /** The name tag on the lit target; the label by default. */
+    targetName?: string;
+}
+export interface LumenOptionGroup<V extends string = string> {
+    label: string;
+    options: readonly LumenOption<V>[];
+}
+interface Common<V extends string> {
+    /** The options; or `groups` to fix the group order. */
+    options?: readonly LumenOption<V>[];
+    groups?: readonly LumenOptionGroup<V>[];
+    /** `field` by default. */
+    trigger?: 'field' | 'chip' | 'icon';
+    /** The icon trigger's icon, or a leading icon in a field or chip. */
+    icon?: Icon;
+    /** `auto`: a search box past 8 options. */
+    search?: 'auto' | boolean;
+    /** Turns typed text into a new value (a ticker, "ema 13", a new sector); null refuses it. */
+    create?: (query: string) => V | null;
+    /** The create row's text; `Add "…"` by default. */
+    createLabel?: (query: string) => string;
+    placeholder?: string;
+    /** Shown when nothing matches. */
+    empty?: string;
+    /** Accessible name; also the phone sheet's title. */
+    label?: string;
+    size?: 'sm' | 'default';
+    className?: string;
+    disabled?: boolean;
+    /** Above the list (a scope switch such as "for SPY / All"). */
+    header?: ReactNode;
+    align?: 'start' | 'end';
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** A row was highlighted (hover or arrow keys): a caller reads it ahead (the assistant's Chats). */
+    onHighlight?: (value: V) => void;
+    id?: string;
+}
+export interface LumenSelectorSingle<V extends string> extends Common<V> {
+    multiple?: false;
+    value: V | null | undefined | '';
+    onChange: (value: V) => void;
+}
+export interface LumenSelectorMulti<V extends string> extends Common<V> {
+    multiple: true;
+    value: readonly V[];
+    onChange: (value: V[]) => void;
+    /** At most this many picked; the rest of the list greys out. */
+    max?: number;
+}
+export type LumenSelectorProps<V extends string = string> = LumenSelectorSingle<V> | LumenSelectorMulti<V>;
+interface Shown<V extends string> {
+    label: string;
+    rows: LumenOption<V>[];
+    more: number;
+}
+/**
+ * How well `q` matches `s` as a subsequence (`prc` finds Price), higher is better; null when it
+ * doesn't. Letters in a row and at word starts score more, a prefix most.
+ */
+export declare function fuzzyScore(q: string, s: string): number | null;
+/**
+ * What the list shows: matching rows by group, a long group cut to 6 (plus any picked row) until
+ * it is opened or searched. Shared by every trigger so rows behave the same.
+ */
+export declare function useSelectorRows<V extends string>(options: readonly LumenOption<V>[] | undefined, groups: readonly LumenOptionGroup<V>[] | undefined, query: string, picked: ReadonlySet<string>, 
+/** Match letters in order, not a substring, and put the best matches first. */
+fuzzy?: boolean): {
+    all: LumenOptionGroup<V>[];
+    shown: Shown<V>[];
+    count: number;
+    flat: LumenOption<V>[];
+    expand: (label: string) => void;
+};
+/** One row's inside: box or icon, label, detail, and the check when picked. */
+export declare function SelectorRowContent({ option, selected, multiple, trailing, }: {
+    option: LumenOption;
+    selected?: boolean;
+    multiple?: boolean;
+    trailing?: ReactNode;
+}): import("react").JSX.Element;
+/** The one picker. See the file header for what every use gets. */
+export declare function LumenSelector<V extends string = string>(props: LumenSelectorProps<V>): import("react").JSX.Element;
+/** What a text box calls on keys while an `LumenSelectorList` shows. */
+export interface LumenSelectorListHandle {
+    /** Handles arrows, Enter, Tab and Esc; true when the key was the list's. */
+    key: (e: {
+        key: string;
+        shiftKey?: boolean;
+        preventDefault: () => void;
+    }) => boolean;
+}
+/**
+ * `trigger="none"`: the list anchored to a text box the page owns (the assistant @ and /). The text box
+ * passes the query and its keys (`handle.key`); Tab or Enter takes the highlighted row, the first
+ * by default.
+ */
+export declare function LumenSelectorList<V extends string = string>({ options, groups, query, onPick, onClose, empty, header, className, handle, label, fuzzy, }: {
+    options?: readonly LumenOption<V>[];
+    groups?: readonly LumenOptionGroup<V>[];
+    query: string;
+    onPick: (option: LumenOption<V>) => void;
+    onClose?: () => void;
+    empty?: string;
+    header?: ReactNode;
+    className?: string;
+    handle?: Ref<LumenSelectorListHandle>;
+    label?: string;
+    /** Letters in order match (`prc` finds Price), best first: autocomplete in a text box. */
+    fuzzy?: boolean;
+}): import("react").JSX.Element;
+export {};