@columenlabs/lumen-ui 0.0.0-stage → 0.2.0

package/dist/lumen-selector.js

@@ -0,0 +1,308 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// LumenSelector: the one
+// picker for every "pick one or more things from a list", on the shell's base-ui Combobox.
+//
+//   - Groups with sticky headings, in the order given; a group over 6 rows shows 6 and "N more"
+//     until searched. Same label twice: `detail` tells them apart (a dev warning when it can't).
+//   - One aligned detail column on the right; the selected row has a muted fill. Only multiple
+//     selection shows checks (a checkbox per row); a single pick never shows a checkmark.
+//   - Search shows past 8 options (`search="auto"`); `create` turns a typed value into an option.
+//   - Single or multiple (chips in the trigger, "+N" past four, Clear all, picked order kept).
+//   - Triggers: `field` (a form select), `chip` (a compact header pill), `icon` (an icon button).
+//     `LumenSelectorList` is the fourth, `none`: the list anchored to a text box (the assistant @ and /).
+//   - Phone: a bottom sheet with the search on top and, for multiple, Done.
+//   - An option with a `target` (a card or a sidebar page) lights it on the page while hovered.
+import { Combobox as Base } from '@base-ui/react';
+import { CheckIcon, ChevronDownIcon, PlusIcon, SearchIcon, XIcon } from 'lucide-react';
+import { useEffect, useId, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState, } from 'react';
+import { useIsMobile } from './hooks/use-mobile.js';
+import { cn } from './lib/utils.js';
+import { spotlight } from './spotlight.js';
+import { Button } from './ui/button.js';
+import { Sheet, SheetContent, SheetDescription, SheetTitle } from './ui/sheet.js';
+import { Tooltip, TooltipContent, TooltipTrigger } from './ui/tooltip.js';
+const SHOWN = 6;
+const SEARCH_PAST = 8;
+const CHIPS = 4;
+const CREATE = '\u0000create';
+/** The options as groups, in order. */
+function toGroups(options, groups) {
+    if (groups)
+        return groups.filter((g) => g.options.length);
+    const byLabel = new Map();
+    for (const o of options ?? []) {
+        const g = o.group ?? '';
+        byLabel.set(g, [...(byLabel.get(g) ?? []), o]);
+    }
+    return [...byLabel].map(([label, list]) => ({ label, options: list }));
+}
+const matches = (o, group, q) => [o.label, o.detail, group, ...(o.keywords ?? [])].some((s) => s?.toLowerCase().includes(q));
+/**
+ * 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 function fuzzyScore(q, s) {
+    const t = s.toLowerCase();
+    if (!q)
+        return 0;
+    if (t === q)
+        return 1000;
+    if (t.startsWith(q))
+        return 500 - t.length;
+    let score = 0;
+    let at = -1;
+    let run = 0;
+    for (const ch of q) {
+        const i = t.indexOf(ch, at + 1);
+        if (i < 0)
+            return null;
+        run = i === at + 1 ? run + 1 : 0;
+        const start = i === 0 || /[\s_.\-%(]/.test(t[i - 1] ?? '');
+        score += 1 + run * 3 + (start ? 5 : 0) - Math.min(i - at - 1, 5) * 0.2;
+        at = i;
+    }
+    return score - t.length * 0.05;
+}
+/** The best fuzzy score of an option over its label, value and keywords. */
+const fuzzyOf = (o, q) => [o.label, o.value, ...(o.keywords ?? [])].reduce((best, s) => {
+    const v = fuzzyScore(q, s);
+    return v === null ? best : best === null ? v : Math.max(best, v);
+}, 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 function useSelectorRows(options, groups, query, picked, 
+/** Match letters in order, not a substring, and put the best matches first. */
+fuzzy = false) {
+    const all = useMemo(() => toGroups(options, groups), [options, groups]);
+    const [open, setOpen] = useState(new Set());
+    const q = query.trim().toLowerCase();
+    const shown = useMemo(() => {
+        if (fuzzy && q) {
+            const scored = all.flatMap((g) => {
+                const rows = g.options
+                    .map((o) => ({ o, v: fuzzyOf(o, q) }))
+                    .filter((r) => r.v !== null)
+                    .sort((a, b) => b.v - a.v);
+                return rows.length ? [{ label: g.label, rows, best: rows[0]?.v ?? 0 }] : [];
+            });
+            return scored
+                .sort((a, b) => b.best - a.best)
+                .map((g) => ({ label: g.label, rows: g.rows.map((r) => r.o), more: 0 }));
+        }
+        return all.flatMap((g) => {
+            const rows = q ? g.options.filter((o) => matches(o, g.label, q)) : [...g.options];
+            if (!rows.length)
+                return [];
+            if (q || open.has(g.label) || rows.length <= SHOWN + 1)
+                return [{ label: g.label, rows, more: 0 }];
+            const keep = rows.filter((o, i) => i < SHOWN || picked.has(o.value));
+            return [{ label: g.label, rows: keep, more: rows.length - keep.length }];
+        });
+    }, [all, q, open, picked, fuzzy]);
+    const count = useMemo(() => all.reduce((n, g) => n + g.options.length, 0), [all]);
+    useDuplicateWarning(all);
+    return {
+        all,
+        shown,
+        count,
+        flat: shown.flatMap((g) => g.rows),
+        expand: (label) => setOpen((s) => new Set([...s, label])),
+    };
+}
+/** Two rows that read the same can't be told apart: say so while building (design rule 2). */
+function useDuplicateWarning(all) {
+    useEffect(() => {
+        if (!import.meta.env?.DEV)
+            return;
+        for (const g of all) {
+            const seen = new Set();
+            for (const o of g.options) {
+                const k = `${o.label}\u0000${o.detail ?? ''}`;
+                if (seen.has(k))
+                    console.warn(`LumenSelector: two "${o.label}" rows in "${g.label}" share their detail`);
+                seen.add(k);
+            }
+        }
+    }, [all]);
+}
+const ROW = 'relative flex w-full cursor-default items-center gap-2 rounded-md px-2 text-sm outline-hidden select-none h-8 max-md:h-11 max-md:px-4 max-md:text-[15px] data-highlighted:bg-accent data-highlighted:text-accent-foreground data-selected:bg-muted data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*=size-])]:size-4';
+/** A row with a description or thumbnail grows to fit it. */
+const TALL = 'h-auto min-h-8 py-1.5 max-md:h-auto';
+const GROUP_LABEL = 'sticky top-0 z-10 bg-popover px-2 pt-2 pb-1 text-xs font-medium text-muted-foreground max-md:px-4';
+const MORE = 'flex h-7 w-full items-center gap-1.5 rounded-md pr-2 pl-8 text-left text-xs text-muted-foreground hover:bg-accent max-md:pl-11';
+/** One row's inside: box or icon, label, detail, and the check when picked. */
+export function SelectorRowContent({ option, selected, multiple, trailing, }) {
+    const Icon = option.icon;
+    return (_jsxs(_Fragment, { children: [option.indent && _jsx("span", { "aria-hidden": true, className: "w-4 shrink-0" }), multiple && (_jsx("span", { "aria-hidden": true, className: cn('flex size-4 shrink-0 items-center justify-center rounded-[4px] border border-input', selected && 'border-primary bg-primary text-primary-foreground'), children: selected && _jsx(CheckIcon, { className: "size-3" }) })), option.thumb ? (_jsx("span", { "aria-hidden": true, className: "shrink-0", children: option.thumb })) : (Icon && _jsx(Icon, { className: "text-muted-foreground" })), option.description ? (_jsxs("span", { className: "flex min-w-0 flex-1 flex-col", children: [_jsx("span", { className: "truncate", children: option.content ?? option.label }), _jsx("span", { className: "truncate text-xs text-muted-foreground", children: option.description })] })) : (_jsx("span", { className: "min-w-0 flex-1 truncate", children: option.content ?? option.label })), option.detail && (_jsx("span", { className: "shrink-0 text-xs whitespace-nowrap text-muted-foreground", children: option.detail })), trailing] }));
+}
+function Rows({ shown, picked, multiple, full, expand, }) {
+    return shown.map((g) => (_jsxs(Base.Group, { items: g.rows.map((o) => o.value), children: [g.label && _jsx(Base.GroupLabel, { className: GROUP_LABEL, children: g.label }), g.rows.map((o) => {
+                const row = (_jsx(Base.Item, { value: o.value, disabled: !!o.disabled || (full && !picked.has(o.value)), className: cn(ROW, (o.description || o.thumb) && TALL), children: _jsx(SelectorRowContent, { option: o, selected: picked.has(o.value), multiple: multiple && o.value !== CREATE }) }, o.value));
+                return typeof o.disabled === 'string' ? (_jsxs(Tooltip, { children: [_jsx(TooltipTrigger, { asChild: true, children: _jsx("div", { children: row }) }), _jsx(TooltipContent, { children: o.disabled })] }, o.value)) : (row);
+            }), g.more > 0 && (_jsxs("button", { type: "button", className: MORE, onMouseDown: (e) => e.preventDefault(), onClick: () => expand(g.label), children: [_jsx(ChevronDownIcon, { className: "size-3.5" }), g.more, " more"] }))] }, g.label || '\u0000')));
+}
+const FIELD = "flex w-fit min-w-0 items-center justify-between gap-1.5 rounded-lg border border-input bg-transparent pr-2 pl-2.5 text-sm whitespace-nowrap transition-colors outline-none select-none dark:bg-input/30 dark:hover:bg-input/50 focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 data-[size=default]:h-8 data-[size=sm]:h-7 data-[size=sm]:rounded-[min(var(--radius-md),10px)] [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4";
+/** The one picker. See the file header for what every use gets. */
+export function LumenSelector(props) {
+    const { options, groups, trigger = 'field', icon: LeadIcon, search = 'auto', create, createLabel = (q) => `Add “${q}”`, placeholder = 'Pick one', empty = 'Nothing matches', label, size = 'default', className, disabled, header, align = 'start', id, } = props;
+    const multiple = props.multiple === true;
+    const values = multiple
+        ? props.value
+        : props.value
+            ? [props.value]
+            : [];
+    const picked = useMemo(() => new Set(values), [values]);
+    const [query, setQuery] = useState('');
+    const chipsRef = useRef(null);
+    const [ownOpen, setOwnOpen] = useState(false);
+    const open = props.open ?? ownOpen;
+    // Inside a modal dialog or sheet, the list portals into it: a modal's focus trap would pull
+    // focus back out of a list portalled to the body, so its search box could never be typed in.
+    const markRef = useRef(null);
+    const [host, setHost] = useState(null);
+    useLayoutEffect(() => {
+        if (open)
+            setHost(markRef.current?.closest('[role="dialog"]') ?? null);
+    }, [open]);
+    const setOpen = (o) => {
+        setOwnOpen(o);
+        props.onOpenChange?.(o);
+        if (!o) {
+            setQuery('');
+            spotlight(null);
+        }
+    };
+    const phone = useIsMobile();
+    const sheetTitle = useId();
+    const { all, shown, count, flat, expand } = useSelectorRows(options, groups, query, picked);
+    const searchable = search === true || (search === 'auto' && count > SEARCH_PAST) || !!create;
+    const byValue = useMemo(() => {
+        const m = new Map();
+        for (const g of all)
+            for (const o of g.options)
+                m.set(o.value, o);
+        return m;
+    }, [all]);
+    const q = query.trim();
+    // The create row shows only for text `create` would take (a known ticker, a valid spec).
+    const canCreate = !!create &&
+        !!q &&
+        !flat.some((o) => o.label.toLowerCase() === q.toLowerCase()) &&
+        create(q) !== null;
+    const rows = canCreate
+        ? [
+            ...shown,
+            {
+                label: '',
+                rows: [{ value: CREATE, label: createLabel(q), icon: PlusIcon }],
+                more: 0,
+            },
+        ]
+        : shown;
+    // Multiple shows chips in the trigger, typed text after them searching; an icon trigger keeps
+    // the search in the popup.
+    const inChips = multiple && trigger !== 'icon';
+    const max = multiple ? props.max : undefined;
+    const full = max !== undefined && values.length >= max;
+    const labelOf = (v) => byValue.get(v)?.label ?? v;
+    const pick = (next) => {
+        const made = (v) => v === CREATE ? (create?.(q) ?? null) : v;
+        if (multiple) {
+            const list = (Array.isArray(next) ? next : []).map(made).filter((v) => v !== null);
+            props.onChange([...new Set(list)]);
+            setQuery('');
+        }
+        else if (typeof next === 'string') {
+            const v = made(next);
+            if (v !== null)
+                props.onChange(v);
+            setOpen(false);
+        }
+    };
+    const selected = multiple ? null : (byValue.get(values[0] ?? '') ?? null);
+    const Lead = selected?.icon ?? LeadIcon;
+    const fieldInside = (_jsxs(_Fragment, { children: [Lead && _jsx(Lead, { className: "text-muted-foreground" }), _jsx("span", { className: cn('min-w-0 flex-1 truncate text-left', !selected && !values.length && 'text-muted-foreground'), children: selected ? (selected.content ?? selected.label) : values[0] ? values[0] : placeholder }), _jsx(ChevronDownIcon, { className: "pointer-events-none size-4 text-muted-foreground" })] }));
+    const list = (_jsxs(_Fragment, { children: [header, _jsx(Base.List, { className: cn('overscroll-contain p-1 data-empty:p-0', phone
+                    ? 'min-h-0 flex-1 overflow-y-auto pb-4'
+                    : 'max-h-[min(22rem,calc(var(--available-height)-3rem))] scroll-pt-8 overflow-y-auto'), children: _jsx(Rows, { shown: rows, picked: picked, multiple: multiple, full: full, expand: expand }) }), _jsx(Base.Empty, { className: "hidden px-2 py-3 text-center text-sm text-muted-foreground group-data-empty/selector:block", children: empty })] }));
+    const clearAll = multiple && values.length > 0 && (_jsx("button", { type: "button", className: "text-xs text-muted-foreground hover:text-foreground", onClick: () => props.onChange([]), children: "Clear all" }));
+    const searchBox = (_jsxs("div", { className: cn('flex items-center gap-2 border-b px-2', phone ? 'mx-4 h-11 rounded-md border' : 'h-9', !searchable && 'sr-only'), children: [_jsx(SearchIcon, { className: "size-4 shrink-0 text-muted-foreground" }), _jsx(Base.Input, { readOnly: !searchable, placeholder: create ? 'Search or type a new one' : `Search ${count}`, "aria-label": label ? `Search ${label}` : 'Search', className: "h-full min-w-0 flex-1 bg-transparent text-sm outline-none placeholder:text-muted-foreground max-md:text-[15px]" })] }));
+    const rootProps = {
+        items: rows.map((g) => ({ value: g.label, items: g.rows.map((o) => o.value) })),
+        filteredItems: rows.map((g) => ({ value: g.label, items: g.rows.map((o) => o.value) })),
+        itemToStringLabel: labelOf,
+        inputValue: query,
+        onInputValueChange: (v) => setQuery(v),
+        open,
+        onOpenChange: setOpen,
+        disabled,
+        autoHighlight: true,
+        onItemHighlighted: (v) => {
+            const o = v ? byValue.get(v) : undefined;
+            spotlight(o?.target, o?.targetName ?? o?.label);
+            if (o && o.value !== CREATE)
+                props.onHighlight?.(o.value);
+        },
+    };
+    // Multiple: chips in the trigger, typed text after them searches.
+    const chips = multiple && (_jsxs(_Fragment, { children: [values.slice(0, CHIPS).map((v) => (_jsxs(Base.Chip, { className: "flex h-[calc(--spacing(5.25))] items-center gap-1 rounded-sm bg-muted px-1.5 text-xs font-medium whitespace-nowrap", children: [labelOf(v), _jsx(Base.ChipRemove, { "aria-label": `Remove ${labelOf(v)}`, className: "-mr-0.5 rounded-sm opacity-50 hover:opacity-100", children: _jsx(XIcon, { className: "size-3" }) })] }, v))), values.length > CHIPS && (_jsxs("span", { className: "rounded-sm bg-muted px-1.5 text-xs leading-[calc(--spacing(5.25))] font-medium", children: ["+", values.length - CHIPS] }))] }));
+    if (phone) {
+        // The trigger opens a bottom sheet; the list is the combobox inline in it.
+        const opener = trigger === 'icon' ? (_jsx(Button, { variant: "ghost", size: "icon-sm", "aria-label": label, disabled: disabled, className: className, onClick: () => setOpen(true), children: LeadIcon && _jsx(LeadIcon, {}) })) : (_jsx("button", { type: "button", id: id, "data-size": size, "aria-label": label, disabled: disabled, className: cn(FIELD, multiple && 'h-auto min-h-8 flex-wrap justify-start py-1', trigger === 'chip' && 'rounded-full', className), onClick: () => setOpen(true), children: multiple ? (values.length ? (_jsxs("span", { className: "flex flex-1 flex-wrap gap-1", children: [values.slice(0, CHIPS).map((v) => (_jsx("span", { className: "rounded-sm bg-muted px-1.5 text-xs leading-[calc(--spacing(5.25))] font-medium", children: labelOf(v) }, v))), values.length > CHIPS && (_jsxs("span", { className: "rounded-sm bg-muted px-1.5 text-xs leading-[calc(--spacing(5.25))]", children: ["+", values.length - CHIPS] }))] })) : (_jsx("span", { className: "flex-1 text-left text-muted-foreground", children: placeholder }))) : (fieldInside) }));
+        return (_jsxs(_Fragment, { children: [opener, _jsx(Sheet, { open: open, onOpenChange: setOpen, children: _jsxs(SheetContent, { side: "bottom", showCloseButton: false, "aria-labelledby": sheetTitle, 
+                        // No ring on the first button: the person taps what they want.
+                        onOpenAutoFocus: (e) => e.preventDefault(), className: "group/selector flex max-h-[85dvh] flex-col gap-2 rounded-t-xl pt-2", children: [_jsx("span", { "aria-hidden": true, className: "mx-auto h-1 w-9 rounded-full bg-border" }), _jsxs("div", { className: "flex items-center justify-between px-4", children: [_jsx(SheetTitle, { id: sheetTitle, children: label ?? placeholder }), multiple && (_jsx(Button, { size: "sm", onClick: () => setOpen(false), children: "Done" }))] }), _jsx(SheetDescription, { className: "sr-only", children: multiple ? 'Pick any, then Done' : 'Pick one' }), _jsxs(Base.Root, { ...rootProps, inline: true, open: true, onOpenChange: () => undefined, multiple: multiple, value: multiple ? [...values] : (values[0] ?? null), onValueChange: (v) => pick(v), children: [multiple && values.length > 0 && (_jsx("div", { className: "flex flex-wrap gap-1.5 px-4", children: values.map((v) => (_jsx("span", { className: "rounded-sm bg-muted px-2 py-1 text-[13px]", children: labelOf(v) }, v))) })), searchable && searchBox, list] }), multiple && (_jsxs("div", { className: "flex items-center justify-between border-t px-4 pt-3 pb-5", children: [_jsxs("span", { className: "text-xs text-muted-foreground", children: [values.length, " picked"] }), clearAll] }))] }) })] }));
+    }
+    const popup = (_jsx(Base.Portal, { container: host ?? undefined, children: _jsx(Base.Positioner, { side: "bottom", sideOffset: 4, align: align, anchor: inChips ? chipsRef : undefined, className: "pointer-events-auto isolate z-[60]", children: _jsxs(Base.Popup, { "data-slot": "lumen-selector", className: "group/selector max-w-(--available-width) min-w-[max(var(--anchor-width),14rem)] origin-(--transform-origin) overflow-hidden rounded-lg bg-popover text-popover-foreground shadow-md ring-1 ring-foreground/10 duration-100 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95", children: [!inChips && searchBox, list, clearAll && (_jsxs("div", { className: "flex items-center justify-between border-t px-2 py-1.5", children: [_jsxs("span", { className: "text-xs text-muted-foreground", children: [values.length, " picked", max !== undefined ? ` of ${max}` : ''] }), clearAll] }))] }) }) }));
+    return (_jsxs(Base.Root, { ...rootProps, multiple: multiple, value: multiple ? [...values] : (values[0] ?? null), onValueChange: (v) => pick(v), children: [inChips ? (_jsxs(Base.Chips, { ref: chipsRef, className: cn('flex min-h-8 flex-wrap items-center gap-1 rounded-lg border border-input bg-transparent px-1 py-1 text-sm transition-colors focus-within:border-ring focus-within:ring-3 focus-within:ring-ring/50 dark:bg-input/30', className), children: [chips, _jsx(Base.Input, { id: id, "aria-label": label, disabled: disabled, readOnly: !searchable, placeholder: values.length ? '' : placeholder, className: "min-w-16 flex-1 bg-transparent px-1 outline-none placeholder:text-muted-foreground" })] })) : trigger === 'icon' ? (_jsxs(Tooltip, { children: [_jsx(TooltipTrigger, { asChild: true, children: _jsx(Base.Trigger, { render: _jsx(Button, { variant: "ghost", size: "icon-sm", "aria-label": label, className: className }), children: LeadIcon && _jsx(LeadIcon, {}) }) }), _jsx(TooltipContent, { children: label })] })) : (_jsx(Base.Trigger, { id: id, "data-size": size, "aria-label": label, className: cn(FIELD, trigger === 'chip' && 'rounded-full', className), children: fieldInside })), _jsx("span", { ref: markRef, hidden: true }), popup] }));
+}
+/**
+ * `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 function LumenSelectorList({ options, groups, query, onPick, onClose, empty, header, className, handle, label, fuzzy, }) {
+    const none = useMemo(() => new Set(), []);
+    const { shown, flat, expand } = useSelectorRows(options, groups, query, none, fuzzy);
+    const [at, setAt] = useState(0);
+    const listId = useId();
+    // biome-ignore lint/correctness/useExhaustiveDependencies: a new query starts at the first row.
+    useEffect(() => setAt(0), [query]);
+    const index = Math.min(at, flat.length - 1);
+    const active = flat[index];
+    useEffect(() => {
+        spotlight(active?.target, active?.targetName ?? active?.label);
+    }, [active]);
+    useEffect(() => () => spotlight(null), []);
+    useImperativeHandle(handle, () => ({
+        key: (e) => {
+            if (!flat.length)
+                return false;
+            if (e.key === 'ArrowDown' || e.key === 'ArrowUp') {
+                e.preventDefault();
+                const step = e.key === 'ArrowDown' ? 1 : -1;
+                setAt((i) => (Math.min(i, flat.length - 1) + step + flat.length) % flat.length);
+                return true;
+            }
+            if ((e.key === 'Enter' && !e.shiftKey) || e.key === 'Tab') {
+                if (!active || active.disabled)
+                    return false;
+                e.preventDefault();
+                onPick(active);
+                return true;
+            }
+            if (e.key === 'Escape' && onClose) {
+                e.preventDefault();
+                onClose();
+                return true;
+            }
+            return false;
+        },
+    }), [flat, active, onPick, onClose]);
+    return (_jsxs("div", { "data-slot": "lumen-selector-list", className: cn('flex max-h-80 flex-col overflow-hidden rounded-lg bg-popover text-popover-foreground shadow-md ring-1 ring-foreground/10', className), children: [header, _jsxs("div", { id: listId, "aria-label": label, className: "min-h-0 overflow-y-auto overscroll-contain p-1", children: [!flat.length && (_jsx("p", { className: "px-2 py-3 text-center text-sm text-muted-foreground", children: empty ?? 'Nothing matches' })), shown.map((g) => (_jsxs("section", { "aria-label": g.label || undefined, children: [g.label && _jsx("div", { className: GROUP_LABEL, children: g.label }), g.rows.map((o) => {
+                                const i = flat.indexOf(o);
+                                return (_jsx("button", { type: "button", tabIndex: -1, "aria-current": i === index || undefined, disabled: !!o.disabled, "data-highlighted": i === index ? '' : undefined, className: cn(ROW, 'text-left'), onMouseMove: () => i !== index && setAt(i), onMouseDown: (e) => e.preventDefault(), onClick: () => !o.disabled && onPick(o), children: _jsx(SelectorRowContent, { option: o, trailing: i === 0 ? (_jsx("kbd", { className: "rounded border px-1 font-mono text-[11px] text-muted-foreground", children: "Tab" })) : undefined }) }, o.value));
+                            }), g.more > 0 && (_jsxs("button", { type: "button", className: MORE, onMouseDown: (e) => e.preventDefault(), onClick: () => expand(g.label), children: [_jsx(ChevronDownIcon, { className: "size-3.5" }), g.more, " more ", g.label.toLowerCase()] }))] }, g.label || '\u0000')))] })] }));
+}

package/dist/lumen-source.d.ts

@@ -0,0 +1,137 @@
+import { type QueryKey, type UseQueryOptions, type UseQueryResult } from '@tanstack/react-query';
+import { type ReactNode } from 'react';
+/** One component's loading state, from `useLumenSource` or `useLumenLoad`. */
+export interface LumenLoad {
+    /** Nothing to show yet: the first load runs, or waits until the card scrolls into view. */
+    loading: boolean;
+    /** A request is in flight (first load or refresh). */
+    fetching: boolean;
+    /** A request is in flight while data is on screen. */
+    refreshing: boolean;
+    /** A background refresh (a poll, refetch on focus) is in flight: silent unless a view shows it. */
+    background: boolean;
+    /** The load failed and there is nothing to show. */
+    error: Error | null;
+    /** A refresh failed; the older data stays on screen. */
+    stale: Error | null;
+    /** Reloads this component's source only, skipping the server cache. */
+    refresh: () => Promise<void>;
+    /** Reads the source again quietly, through the server cache (a live view's poll). */
+    poll?: () => void;
+    /** The last load, request start to data, in ms; null before the first. */
+    tookMs: number | null;
+    /** The data on screen came from this browser's cache, with no request. */
+    cached: boolean;
+    /** When the data on screen arrived (ms since epoch); null before the first. */
+    at: number | null;
+    /**
+     * When the source itself was last updated, apart from when this browser loaded it (the assistant
+     * frame's last run of its script): the card's header shows it as a signal dot, its time and why
+     * its last update failed on hover. `live` sources are fresh for 5 minutes,
+     * others for the day; `fixed` ones never go stale; `about` is one line on what the source is.
+     */
+    /**
+     * Opens the code that makes this source (the assistant frame's script) to read and edit; the signal dot's
+     * popover and the card's ⋯ menu offer it.
+     */
+    editScript?: () => void;
+    updated?: {
+        at: number;
+        error?: string | null;
+        kind?: 'live' | 'asof' | 'fixed';
+        about?: string;
+    };
+    /** What the card's ↻ does, when it is more than a reload (the assistant frame runs its script again). */
+    refreshLabel?: string;
+}
+/** What `useLumenLoad` reads of a TanStack query. */
+type QueryState = Pick<UseQueryResult<unknown, unknown>, 'data' | 'error' | 'isError' | 'isFetching' | 'dataUpdatedAt' | 'refetch'> & Partial<Pick<UseQueryResult<unknown, unknown>, 'isPlaceholderData'>>;
+/** The loading state of queries a page already runs (rows built from several reads). */
+export declare function useLumenLoad(...queries: QueryState[]): LumenLoad;
+/**
+ * Cards that draw one shared source (a view and the widgets over its rows). A card's ↻ still reloads
+ * that source, since every card draws the same rows, but only the card that asked spins, dims and
+ * shows the new load time; the others keep still with their own last time and take the new rows
+ * quietly. A reload no card asked for (the page's Refresh, a refetch) shows on every card. Returns a
+ * function giving each card its own load.
+ */
+export declare function useCardLoads(): (id: string, load: LumenLoad | undefined) => LumenLoad | undefined;
+/** Runs one source. `lazy` holds the query until the card (`ref`) scrolls into view. */
+export declare function useLumenSource<TQueryFnData, TError, TData, TKey extends QueryKey>(options: UseQueryOptions<TQueryFnData, TError, TData, TKey>, { lazy }?: {
+    lazy?: boolean;
+}): {
+    data: TData | undefined;
+    load: LumenLoad;
+    ref: (node?: Element | null) => void;
+};
+/** Mounts `children` once they scroll into view: cards whose data is their own (live market). */
+export declare function LumenLazy({ children, fallback, }: {
+    children: ReactNode;
+    fallback?: ReactNode;
+}): import("react").JSX.Element;
+/** The thin indeterminate bar along the top of a view while its query runs. */
+export declare function LumenProgress({ load }: {
+    load: LumenLoad;
+}): import("react").JSX.Element | null;
+/** ↻ for one card or view: reloads its source past the server cache, spinning while it runs. */
+export declare function LumenRefresh({ load, label }: {
+    load: LumenLoad;
+    label?: string;
+}): import("react").JSX.Element;
+/** The load time line (`1.8 s · 412 rows · 12:41:08 Pacific`), only with Observability details on. */
+export declare function LumenLoadTime({ load, rows, className, }: {
+    load: LumenLoad;
+    rows?: number;
+    className?: string;
+}): import("react").JSX.Element | null;
+/** A failed source, inside its own card, with Retry. */
+export declare function LumenError({ error, onRetry }: {
+    error: Error;
+    onRetry?: () => void;
+}): import("react").JSX.Element;
+/** Rows of skeleton the height of a table, so nothing jumps when the data lands. */
+export declare function LumenSkeleton({ rows, className }: {
+    rows?: number;
+    className?: string;
+}): import("react").JSX.Element;
+/** One component's states from its load: bar (views), skeleton, error with Retry, empty, then the
+ *  content, dimmed while it refreshes. Place it at the top of a `relative` card body. */
+export declare function LumenStates({ load, kind, skeleton, empty, children, }: {
+    load: LumenLoad;
+    /** Views (tables, grids) carry the progress bar; widgets a skeleton and their spinning ↻. */
+    kind?: 'table' | 'widget';
+    skeleton?: ReactNode;
+    /** Shown in place of the content when the source loaded nothing. */
+    empty?: ReactNode;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** A card's footer line with its load time, rows and clock time, only with Observability details on. */
+export declare function LumenLoadFooter({ load, rows, note, }: {
+    load: LumenLoad;
+    rows?: number;
+    /** Said instead of rows, e.g. a chart drawn from its view's rows. */
+    note?: string;
+}): import("react").JSX.Element | null;
+/** How often a view showing live columns reads its source again while the market trades. */
+export declare const LIVE_POLL_MS = 60000;
+/**
+ * When US stocks trade at all: pre-market, the session, after-hours and the
+ * overnight session run from 8:00 PM New York on Sunday to 8:00 PM on Friday (holidays not known here).
+ */
+export declare function marketTrades(at?: number): boolean;
+/**
+ * A view's load while it shows live columns (#861): while the market trades and
+ * the tab shows, it reads its source again every minute, quietly, and the card's header carries the
+ * green signal dot (Live, with when it last updated). Extended hours and overnight poll too (the
+ * app's feed decides whether prices move then); over the weekend nothing polls.
+ */
+export declare function useLiveLoad(load: LumenLoad | undefined, live: boolean): LumenLoad | undefined;
+/**
+ * The card header's signal dot for a source with its own update time (`load.updated`): green while
+ * fresh, amber once stale (worth a ↻), red when its last update failed, grey for data that never
+ * updates; hover (a tap on phone) says when, what and why.
+ */
+export declare function LumenFreshness({ load }: {
+    load: LumenLoad;
+}): import("react").JSX.Element | null;
+export {};