@columenlabs/lumen-ui 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Columen Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,12 @@
+Lumen
+Copyright (c) 2026 Columen Labs. Licensed under the MIT License (see LICENSE).
+
+Lumen draws price and market charts with TradingView Lightweight Charts™
+(https://github.com/tradingview/lightweight-charts), Copyright (c) 2025
+TradingView, Inc., licensed under the Apache License 2.0. Lumen turns off the
+chart's own logo, so per that library's NOTICE, an app that shows these charts
+should link to https://www.tradingview.com/ somewhere a user can find it (an
+About page or footer is enough).
+
+The components under packages/lumen/src/ui are based on shadcn/ui
+(https://ui.shadcn.com), MIT License, Copyright (c) 2023 shadcn.

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @columenlabs/lumen-ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Lumen's components: the app frame (`LumenShell`), pages and views (`LumenLayout`, `LumenView`, `LumenTable`, `LumenWidget`, `LumenCard`), charts (`LumenChart`), `LumenDrawer`, `LumenSelector`, the shadcn parts under `ui/*` and one `theme.css`. Its types are in `@columenlabs/lumen-ui-types`.
+
+See the [Lumen README](https://github.com/columenlabs/lumen-ui#readme) for install and use. MIT.

package/dist/add-column.d.ts

@@ -0,0 +1,23 @@
+import type { YourColumn } from '@columenlabs/lumen-ui-types/frames';
+import type { ViewFormula } from '@columenlabs/lumen-ui-types/views';
+import type { ViewDomain } from './view-model.js';
+/** A new formula column: label, key, expression, format and roll-up, checked before Add. */
+export declare function AddFormulaDialog<T>({ open, onOpenChange, domain, formulas, onAdd, }: {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    /** The domain with its join fields (not its formulas), for the keys a formula can read. */
+    domain: ViewDomain<T>;
+    /** The view's formulas so far: their keys are taken, and readable. */
+    formulas: ViewFormula[];
+    onAdd: (formula: ViewFormula) => void;
+}): import("react").JSX.Element;
+/** A Your data column: its name and whether it holds numbers or text. */
+export declare function YourDataDialog({ open, onOpenChange, keyLabel, busy, error, onAdd, }: {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    /** What a row is keyed by: `symbol` or `account`, for the line under the form. */
+    keyLabel: string;
+    busy?: boolean;
+    error?: string | null;
+    onAdd: (column: YourColumn) => void;
+}): import("react").JSX.Element;

package/dist/add-column.js

@@ -0,0 +1,62 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { HashIcon, TypeIcon } from 'lucide-react';
+import { useEffect, useState } from 'react';
+import { useAssistantName } from './assistant-context.js';
+import { SaveButton } from './form-issues.js';
+import { LumenSelector } from './lumen-selector.js';
+import { Button } from './ui/button.js';
+import { Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, } from './ui/dialog.js';
+import { Input } from './ui/input.js';
+import { Label } from './ui/label.js';
+import { FormulaForm, formulaIssueTarget, formulaIssues, formulaOptions } from './view-formulas.js';
+/** A new formula column: label, key, expression, format and roll-up, checked before Add. */
+export function AddFormulaDialog({ open, onOpenChange, domain, formulas, onAdd, }) {
+    const fieldKeys = domain.fields.map((f) => f.key);
+    const fresh = () => {
+        let n = formulas.length + 1;
+        while ([...fieldKeys, ...formulas.map((f) => f.key)].includes(`formula_${n}`))
+            n++;
+        return { key: `formula_${n}`, label: `Formula ${n}`, expr: '', format: 'number', agg: null };
+    };
+    const [draft, setDraft] = useState(fresh);
+    // biome-ignore lint/correctness/useExhaustiveDependencies: a fresh draft each time it opens
+    useEffect(() => {
+        if (open)
+            setDraft(fresh());
+    }, [open]);
+    const issue = formulaIssues([...formulas, draft], domain)[formulas.length] ?? null;
+    const readable = formulaOptions(domain, formulas);
+    return (_jsx(Dialog, { open: open, onOpenChange: onOpenChange, children: _jsxs(DialogContent, { className: "flex max-h-[calc(100svh-2rem)] flex-col gap-0 [--dialog-pad:0px] sm:max-w-2xl max-md:h-svh max-md:max-h-svh max-md:max-w-full max-md:rounded-none", children: [_jsxs(DialogHeader, { className: "border-b px-4 py-3", children: [_jsx(DialogTitle, { className: "text-sm", children: "Add a formula column" }), _jsx(DialogDescription, { children: "A column computed from the other columns, like weight or upside. Saved with the view." })] }), _jsx("div", { className: "min-h-0 flex-1 overflow-y-auto", children: _jsx(FormulaForm, { formula: draft, issue: issue, fields: readable, onChange: (p) => setDraft({ ...draft, ...p }) }) }), _jsxs(DialogFooter, { className: "border-t px-4 py-3", children: [_jsx(Button, { variant: "outline", size: "sm", onClick: () => onOpenChange(false), children: "Cancel" }), _jsx(SaveButton, { label: "Add column", icon: null, issues: issue
+                                ? [
+                                    {
+                                        where: `Formula ${draft.label || draft.key}`,
+                                        message: issue,
+                                        target: formulaIssueTarget(draft.key, issue),
+                                    },
+                                ]
+                                : [], onSave: () => onAdd(draft) })] })] }) }));
+}
+/** A Your data column: its name and whether it holds numbers or text. */
+export function YourDataDialog({ open, onOpenChange, keyLabel, busy, error, onAdd, }) {
+    const assistantName = useAssistantName();
+    const [label, setLabel] = useState('');
+    const [type, setType] = useState('number');
+    useEffect(() => {
+        if (open) {
+            setLabel('');
+            setType('number');
+        }
+    }, [open]);
+    const ok = label.trim().length > 0 && label.trim().length <= 40;
+    const submit = () => {
+        if (ok && !busy)
+            onAdd({ label: label.trim(), type });
+    };
+    return (_jsx(Dialog, { open: open, onOpenChange: onOpenChange, children: _jsxs(DialogContent, { className: "sm:max-w-md", children: [_jsxs(DialogHeader, { children: [_jsx(DialogTitle, { className: "text-sm", children: "Add your own column" }), _jsxs(DialogDescription, { children: ["A column you type into, cell by cell. It stays on every ", keyLabel, " across your cards, and ", assistantName, " reads it but never writes over it."] })] }), _jsxs("form", { className: "grid gap-4", onSubmit: (e) => {
+                        e.preventDefault();
+                        submit();
+                    }, children: [_jsxs("div", { className: "grid gap-1.5", children: [_jsx(Label, { htmlFor: "yours-label", children: "Name" }), _jsx(Input, { id: "yours-label", autoFocus: true, value: label, maxLength: 40, placeholder: "My target", onChange: (e) => setLabel(e.target.value) })] }), _jsxs("div", { className: "grid gap-1.5", children: [_jsx(Label, { children: "Holds" }), _jsx(LumenSelector, { options: [
+                                        { value: 'number', label: 'Numbers', icon: HashIcon },
+                                        { value: 'text', label: 'Text', icon: TypeIcon },
+                                    ], value: type, onChange: (v) => setType(v) })] }), error && (_jsx("p", { role: "alert", className: "text-destructive text-xs", children: error })), _jsxs(DialogFooter, { children: [_jsx(Button, { type: "button", variant: "outline", size: "sm", onClick: () => onOpenChange(false), children: "Cancel" }), _jsx(Button, { type: "submit", size: "sm", disabled: !ok || busy, children: "Add column" })] })] })] }) }));
+}

package/dist/api-fetch.d.ts

@@ -0,0 +1,9 @@
+export declare class ApiError extends Error {
+    readonly method: string;
+    readonly url: string;
+    readonly status: number;
+    readonly code?: string;
+    constructor(message: string, method: string, url: string, status: number, code?: string);
+}
+/** A JSON request; `where` names the caller in the error log (`assistant.undo`, `workspace.read`). */
+export declare function apiJson<T>(url: string, init?: RequestInit, where?: string): Promise<T>;

package/dist/api-fetch.js

@@ -0,0 +1,60 @@
+/**
+ * One JSON fetch for the assistant, workspaces and joins. A failure throws `ApiError` with the
+ * method, address, status and the server's `error` and `code`, so a caller shows what failed and
+ * Workers Logs keep it: a server fault (5xx) or a network failure is reported to
+ * `/api/client-error` with `where` naming the caller. A 4xx is the server saying why it refused,
+ * shown to the person and not logged as a fault.
+ */
+import { reportError } from './route-error.js';
+export class ApiError extends Error {
+    method;
+    url;
+    status;
+    code;
+    constructor(message, method, url, status, code) {
+        super(message);
+        this.method = method;
+        this.url = url;
+        this.name = 'ApiError';
+        this.status = status;
+        this.code = code;
+    }
+}
+/** A JSON request; `where` names the caller in the error log (`assistant.undo`, `workspace.read`). */
+export async function apiJson(url, init = {}, where = 'api') {
+    const method = (init.method ?? 'GET').toUpperCase();
+    let res;
+    try {
+        res = await fetch(url, {
+            ...init,
+            headers: {
+                accept: 'application/json',
+                ...(init.body ? { 'content-type': 'application/json' } : {}),
+                ...(init.headers ?? {}),
+            },
+        });
+    }
+    catch (err) {
+        if (err.name === 'AbortError')
+            throw err;
+        const e = new ApiError(`Couldn't reach the server (${method} ${url})`, method, url, 0);
+        reportError(e, 'shown', where);
+        throw e;
+    }
+    const text = await res.text();
+    let body = null;
+    try {
+        body = text ? JSON.parse(text) : null;
+    }
+    catch {
+        body = null;
+    }
+    if (!res.ok) {
+        const b = (body ?? {});
+        const e = new ApiError(b.error ?? `${method} ${url} answered ${res.status}`, method, url, res.status, b.code);
+        if (res.status >= 500)
+            reportError(e, 'shown', where);
+        throw e;
+    }
+    return body;
+}

package/dist/app-switcher.d.ts

@@ -0,0 +1,21 @@
+import { type LucideIcon } from 'lucide-react';
+import type { ReactNode } from 'react';
+/** One app of the product. */
+export interface LumenApp {
+    id: string;
+    /** Its plain name, for the collapsed sidebar's tooltip. */
+    name: string;
+    /** How its name is drawn (e.g. the app's accent, then a shared suffix); `name` when left out. */
+    label?: ReactNode;
+    icon: LucideIcon;
+    href: string;
+}
+export declare function LumenAppSwitcher({ current, apps, product, menuLabel, }: {
+    /** The app this page belongs to; it leads `apps` even when the menu leaves it out. */
+    current: LumenApp;
+    /** The apps the menu lists, in order. */
+    apps: LumenApp[];
+    /** The product's name under the app's. */
+    product?: string;
+    menuLabel?: string;
+}): import("react").JSX.Element;

package/dist/app-switcher.js

@@ -0,0 +1,12 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// The app switcher (in Lumen for any product with more than one app): the
+// sidebar's top shows the current app and opens a menu of the product's apps. LumenShell's `brand`
+// takes it; the product passes the apps the person can open.
+import { ChevronsUpDownIcon } from 'lucide-react';
+import { cn } from './lib/utils.js';
+import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuLabel, DropdownMenuTrigger, } from './ui/dropdown-menu.js';
+import { SidebarMenu, SidebarMenuButton, SidebarMenuItem, useSidebar } from './ui/sidebar.js';
+export function LumenAppSwitcher({ current, apps, product, menuLabel = 'Apps', }) {
+    const { isMobile } = useSidebar();
+    return (_jsx(SidebarMenu, { children: _jsx(SidebarMenuItem, { children: _jsxs(DropdownMenu, { children: [_jsx(DropdownMenuTrigger, { asChild: true, children: _jsxs(SidebarMenuButton, { size: "lg", tooltip: current.name, className: "data-[state=open]:bg-sidebar-accent data-[state=open]:text-sidebar-accent-foreground", children: [_jsx("div", { className: "flex aspect-square size-8 items-center justify-center rounded-lg bg-sidebar-primary text-sidebar-primary-foreground", children: _jsx(current.icon, { className: "size-4" }) }), _jsxs("div", { className: "grid flex-1 text-left text-sm leading-tight", children: [_jsx("span", { className: "truncate font-semibold", children: current.label ?? current.name }), product && (_jsx("span", { className: "truncate text-xs text-muted-foreground", children: product }))] }), _jsx(ChevronsUpDownIcon, { className: "ml-auto" })] }) }), _jsxs(DropdownMenuContent, { className: "min-w-56 rounded-lg", align: "start", side: isMobile ? 'bottom' : 'right', sideOffset: 4, children: [_jsx(DropdownMenuLabel, { className: "text-xs text-muted-foreground", children: menuLabel }), apps.map((a) => (_jsx(DropdownMenuItem, { asChild: true, className: cn('gap-2 p-2', a.id === current.id && 'bg-muted'), children: _jsxs("a", { href: a.href, "aria-current": a.id === current.id ? 'page' : undefined, children: [_jsx("div", { className: "flex size-6 items-center justify-center rounded-md border", children: _jsx(a.icon, { className: "size-3.5 shrink-0" }) }), a.label ?? a.name] }) }, a.id)))] })] }) }) }));
+}

package/dist/app-views.d.ts

@@ -0,0 +1,18 @@
+import type { CustomView, CustomViewConfig } from '@columenlabs/lumen-ui-types/views';
+/** What a page passes to LumenLayout for an app view: the view as this person has it, its save and its reset. */
+/** An app view as `appView` gives it, or as an app keeps it with its dates. */
+type AnyView = Omit<CustomView, 'created_at' | 'updated_at'>;
+export interface AppViewState<V extends AnyView> {
+    view: V | undefined;
+    /** Saves the person's version of the page. */
+    onConfigChange?: (config: CustomViewConfig) => void;
+    /** Puts the page back to its default; only once the person has changed it. */
+    onReset?: () => void;
+}
+/**
+ * The person's version of `app` (an app view from `appView`, undefined when the page shows another
+ * view): drawn from the code at once, then from the server once read. `enabled` false keeps the
+ * code's (a page that is a workspace tab, an app without the store).
+ */
+export declare function useAppView<V extends AnyView>(app: V | undefined, enabled?: boolean): AppViewState<V>;
+export {};

package/dist/app-views.js

@@ -0,0 +1,41 @@
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { apiJson } from './api-fetch.js';
+const BASE = '/api/app-views';
+/**
+ * The person's version of `app` (an app view from `appView`, undefined when the page shows another
+ * view): drawn from the code at once, then from the server once read. `enabled` false keeps the
+ * code's (a page that is a workspace tab, an app without the store).
+ */
+export function useAppView(app, enabled = true) {
+    const qc = useQueryClient();
+    const url = app && `${BASE}/${app.domain}/${app.id}`;
+    const key = ['app-view', app?.domain, app?.id];
+    const q = useQuery({
+        queryKey: key,
+        queryFn: () => apiJson(url, {}, 'app_view.read'),
+        enabled: !!app && enabled,
+    });
+    const put = (v) => qc.setQueryData(key, v);
+    const save = useMutation({
+        mutationFn: (config) => apiJson(url, { method: 'PUT', body: JSON.stringify({ config }) }, 'app_view.save'),
+        onMutate: (config) => {
+            const now = q.data ?? app;
+            if (now)
+                put({ ...now, config: config, customized: true });
+        },
+        onSuccess: put,
+        onError: () => qc.invalidateQueries({ queryKey: key }),
+    });
+    const reset = useMutation({
+        mutationFn: () => apiJson(url, { method: 'DELETE' }, 'app_view.reset'),
+        onSuccess: put,
+    });
+    if (!app || !enabled)
+        return { view: app };
+    const view = q.data ?? app;
+    return {
+        view,
+        onConfigChange: (config) => save.mutate(config),
+        onReset: view.customized ? () => reset.mutate() : undefined,
+    };
+}

package/dist/assistant-context.d.ts

@@ -0,0 +1,72 @@
+import type { AssistantPageType } from './assistant-screen.js';
+/** What one part of the screen tells the assistant: a short label for the chip and data for the model. */
+export interface AssistantNote {
+    label: string;
+    data?: Record<string, unknown>;
+}
+/**
+ * What the person points at with @: the page, a card on it, a page of the app (a symbol, a
+ * screener, a saved view...), a workspace or one of its tabs, or a Settings section. The assistant reads
+ * what each is and how to reach its data.
+ */
+export type AssistantRef = {
+    kind: 'page';
+    label: string;
+    path: string;
+} | {
+    kind: 'card';
+    label: string;
+    id: string;
+    card?: string;
+    where?: string;
+} | {
+    kind: 'view';
+    label: string;
+    path: string;
+    type?: AssistantPageType;
+    where?: string;
+} | {
+    kind: 'workspace';
+    label: string;
+    workspace: string;
+} | {
+    kind: 'tab';
+    label: string;
+    workspace: string;
+    tab: string;
+    where?: string;
+} | {
+    kind: 'setting';
+    label: string;
+    section: string;
+};
+/** Where a note comes from: the page, or the view on it. */
+export type AssistantSlot = 'page' | 'view';
+/** What pages may call: the same functions for the life of the shell, so pages never redraw. */
+export interface AssistantActions {
+    /** The assistant's name, as people see it: `Atlas`. */
+    name: string;
+    /** The assistant's API base on this app (workspaces and frames live under it). */
+    api: string;
+    note: (slot: AssistantSlot, note: AssistantNote | null) => void;
+    loadChat: (id: string) => void;
+    setOpen: (open: boolean) => void;
+    /** The assistant answers on this app (its status loaded): cards show ✦ Ask the assistant only then. */
+    ready: boolean;
+    /**
+     * Opens the panel with the card's @ chips and a suggested message in the composer, for the person
+     * to edit and send (a card's ⋯ ▸ Ask the assistant; never sent on the tap).
+     */
+    draft: (text: string, refs: AssistantRef[]) => void;
+}
+export declare const AssistantContext: import("react").Context<AssistantActions | null>;
+/** The assistant's stable actions for pages (open a chat, open the panel); null where the app has no assistant. */
+export declare function useAssistant(): AssistantActions | null;
+/** A page (or one part of it) tells the assistant what the person sees; cleared when it unmounts. */
+export declare function useAssistantNote(slot: AssistantSlot, note: AssistantNote | null): void;
+/** The docked assistant's name, or `fallback` where the app has none. */
+export declare function useAssistantName(fallback?: string): string;
+/** True while the app is still finding out whether its assistant answers: a page that needs it
+ *  waits instead of saying it is missing. */
+export declare const AssistantPendingContext: import("react").Context<boolean>;
+export declare function useAssistantPending(): boolean;

package/dist/assistant-context.js

@@ -0,0 +1,30 @@
+// The assistant's place in Lumen: the contract pages and cards use to talk to an
+// assistant, with nothing of the assistant itself. A product that docks one (the product's assistant panel)
+// provides `AssistantContext`; without it every hook here is a no-op and cards hide Ask the assistant.
+import { createContext, useContext, useEffect } from 'react';
+export const AssistantContext = createContext(null);
+/** The assistant's stable actions for pages (open a chat, open the panel); null where the app has no assistant. */
+export function useAssistant() {
+    return useContext(AssistantContext);
+}
+/** A page (or one part of it) tells the assistant what the person sees; cleared when it unmounts. */
+export function useAssistantNote(slot, note) {
+    const set = useContext(AssistantContext)?.note;
+    const key = note ? JSON.stringify(note) : '';
+    useEffect(() => {
+        if (!set)
+            return;
+        set(slot, key ? JSON.parse(key) : null);
+        return () => set(slot, null);
+    }, [set, slot, key]);
+}
+/** The docked assistant's name, or `fallback` where the app has none. */
+export function useAssistantName(fallback = 'the assistant') {
+    return useContext(AssistantContext)?.name ?? fallback;
+}
+/** True while the app is still finding out whether its assistant answers: a page that needs it
+ *  waits instead of saying it is missing. */
+export const AssistantPendingContext = createContext(false);
+export function useAssistantPending() {
+    return useContext(AssistantPendingContext);
+}

package/dist/assistant-panel.d.ts

@@ -0,0 +1,58 @@
+import { type ReactNode } from 'react';
+/** A value kept for this browser tab (sessionStorage), read with `use` and set with `write`. */
+export declare function tabState<T>(key: string, fallback: T, parse: (raw: string) => T | null): {
+    write: (next: T) => void;
+    use: () => T;
+    get: () => T;
+};
+/** Whether the assistant is open in this tab. */
+export declare const assistantOpen: {
+    write: (next: boolean) => void;
+    use: () => boolean;
+    get: () => boolean;
+};
+/** ⌘J (Ctrl+J) calls `toggle` anywhere in the app. */
+export declare function useAssistantHotkey(toggle: () => void): void;
+/** The page header's ✦ button: shown while the assistant is closed, with a dot when a reply came. */
+export declare function LumenAssistantButton({ name, open, unread, onOpen, className, }: {
+    name: string;
+    open: boolean;
+    unread?: boolean;
+    onOpen: () => void;
+    className?: string;
+}): import("react").JSX.Element | null;
+/**
+ * Docked right of the page on desktop (nothing while closed); a full-height sheet on phone, with
+ * `closedBar` under the page while it is closed. `children` draws the body; it is told which.
+ */
+export declare function LumenAssistantPanel({ name, open, onOpenChange, closedBar, children, }: {
+    name: string;
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    /** Shown on phone while closed (the product's one-line screen-move bar). */
+    closedBar?: ReactNode;
+    children: (phone: boolean) => ReactNode;
+}): import("react").JSX.Element | null;
+/** One chat in the history menu. */
+export interface AssistantChat {
+    id: string;
+    title: string;
+    /** ISO time of its last message. */
+    updated_at: string;
+}
+/**
+ * Chats, a dropdown from the panel header: chats grouped by when they were
+ * last used, searched by title. A row is read ahead when highlighted, so picking it opens at once.
+ */
+export declare function LumenAssistantChats<C extends AssistantChat>({ chats, value, note, disabled, onOpen, onRefresh, onHighlight, }: {
+    /** null while loading. */
+    chats: C[] | null;
+    value?: string;
+    /** A line above the list: how long chats are kept. */
+    note?: ReactNode;
+    disabled?: boolean;
+    onOpen: (chat: C) => void;
+    /** The menu opened: read the list again. */
+    onRefresh?: () => void;
+    onHighlight?: (chat: C) => void;
+}): import("react").JSX.Element;