@columenlabs/lumen-ui 0.1.25 → 0.1.27

package/README.md

@@ -1,5 +1,85 @@
 # @columenlabs/lumen-ui
 
-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`.
+Lumen's React components for data apps: the app frame, pages and views over your rows, widgets, charts, drawers and pickers, all on one theme. You give it data and a view config; it draws the screen. Built on [shadcn/ui](https://ui.shadcn.com) (Radix UI, Base UI, Tailwind CSS 4). Its view model is [`@columenlabs/lumen-ui-types`](https://www.npmjs.com/package/@columenlabs/lumen-ui-types).
 
-See the [Lumen README](https://github.com/columenlabs/lumen#readme) for install and use. MIT.
+- Docs and live examples: https://lumen.columenlabs.com/docs/
+- For agents: https://lumen.columenlabs.com/llms.txt
+- Source: https://github.com/columenlabs/lumen (`packages/ui`). MIT.
+
+## Install
+
+Pin both packages to the same exact version.
+
+```bash
+bun add @columenlabs/lumen-ui @columenlabs/lumen-ui-types
+bun add react react-dom @tanstack/react-query @tanstack/react-router   # peers
+bun add -d tailwindcss @tailwindcss/vite tw-animate-css shadcn
+```
+
+## Set up
+
+`src/index.css`:
+
+```css
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "shadcn/tailwind.css";
+@import "@columenlabs/lumen-ui/theme.css";
+@source "../node_modules/@columenlabs/lumen-ui/dist";
+
+/* your accent, per app (LumenShell sets data-app on <html>) */
+:root[data-app="myapp"] { --primary: oklch(0.55 0.15 160); }
+```
+
+At start, before anything renders, tell the kit about your app. The kit names no product: your names and data come in here.
+
+```ts
+import { configureLumen } from '@columenlabs/lumen-ui';
+import { registerDomains } from '@columenlabs/lumen-ui-types/registry';
+
+configureLumen({ prefsCookie: 'myapp_prefs' });   // where display preferences live
+registerDomains({ /* your joins, sources and domain keys */ });
+```
+
+Wrap your routes in the shell:
+
+```tsx
+import { LumenShell } from '@columenlabs/lumen-ui';
+
+<LumenShell app="myapp" appLabel="My app" brand={<Logo />} nav={nav} user={{ email, name }}>
+  <Outlet />
+</LumenShell>
+```
+
+Your own parts go in `LumenShell`'s slots: `brand`, `headerActions`, `panel` (a side panel such as an assistant), `wrap` (providers around the page), `shared`, `profile` (the profile menu) and `statusEnd` (the right end of the status bar).
+
+Use `createDeskQueryClient()` for the app's TanStack Query client: data stays fresh 5 minutes and cached 30.
+
+## What's inside
+
+**Frame.** `LumenShell` (sidebar with icons-only collapse and a drawer on phone, header, status bar, Settings, profile menu, ⌘K Find), `LumenAppSwitcher`, `WhatsNew` (release notes in a drawer), `TasksButton` and `TasksProvider` (background work in the header), `NotificationsSettings`, `McpSettings`, sign-in screens (`LumenAuthStage`, `LumenSecondStep`, `LumenSignInMethods`, `LumenBackupCodes`), `StatusHealth`, `LumenBoundary` (keeps a crash inside its card), `LumenPageState` (loading, empty and error), `lumenToast`.
+
+**Pages and views.** `LumenLayout` (a page of cards from one view config: filter, tiles, widgets; Edit layout and Edit widget when you pass `onConfigChange`), `LumenGrid` (the 6-column grid under it), `LumenView` and `LumenViewCard` (a table that filters, groups, pivots and totals the rows you load), `LumenTable`, `LumenTokenizedFilter`, `LumenWidget` and `LumenSavedWidget` (the frame every card sits in, with its link square and controls), `LumenCard` (one number and its lines), `LumenPager`, `DetailsTable`, `LumenTree`, `useAppView` (a page whose layout each person can change and reset).
+
+**Charts.** `LumenChart` (one or more symbols' prices, with indicators), `LumenEChart`, `LumenGeoMap`, growth and price charts, `StackedBars`, `StackedColumns`, `RankedBars`.
+
+**Pickers and panels.** `LumenSelector` (every picker), `LumenDrawer` with `DrawerSection` (a side panel on desktop, a sheet on phone), `LumenTabs`, `LumenConfirm` (destructive confirms), `LumenForm`, `LumenDateInput`, `LumenChoice`, `LumenSecret`, `RenameField`, `ResetButton`, `SaveButton` with `FormIssue` (a Save that says why it can't), `IconPicker`.
+
+**Primitives.** The shadcn parts under `@columenlabs/lumen-ui/ui/*` (`ui/button`, `ui/badge`, `ui/input`, ...) and `theme.css` (light and dark tokens).
+
+Every export, its props and an example are on the [docs](https://lumen.columenlabs.com/docs/) and in [`llms-full.txt`](https://lumen.columenlabs.com/llms-full.txt).
+
+## Rules the kit follows, and apps should too
+
+- Pickers are `LumenSelector`, side panels `LumenDrawer`, tabs `LumenTabs`, destructive confirms `LumenConfirm`; reach for the raw `ui/*` part only when no Lumen part fits.
+- Every card body sits in `LumenBoundary`, so one crash never blanks a page.
+- Numbers use tabular figures and a true minus `−`; a gain or loss always shows a sign or arrow.
+- A Save blocked by its form's checks is a `SaveButton` that lists each issue, never a bare `disabled`.
+
+## Notices
+
+Charts use TradingView Lightweight Charts™ with its logo off. Please link to https://www.tradingview.com/ somewhere in your app (see NOTICE).
+
+## Versions
+
+0.x: any minor may break things until 1.0. Every merge to Lumen's `main` publishes the next patch of every Lumen package; see the [releases](https://github.com/columenlabs/lumen/releases).

package/dist/index.d.ts

@@ -35,7 +35,7 @@ export { type ChartBand, type ChartMarker, GrowthChart, KEY_DATE_KINDS, KeyDateC
 export { FoldGroup, NavGroup, type NavItem, type SectionItem, type SectionSubItem, SidebarSection, } from './nav.js';
 export { type OverviewPageProps, type OverviewStage, type OverviewTone, type OverviewWidget, OverviewList, OverviewPage, ToneDot, } from './overview.js';
 export { type Crumb, IconButton, type IconButtonProps, Page, PageBody, PageHeader, type PageHeaderProps, } from './page.js';
-export { DEFAULT_PREFS, type Prefs, TIME_ZONES, type Theme, type TimeZoneId, getPrefs, resolvedTheme, setPref, timeZoneLabel, usePrefs, ASSISTANT_WIDTH, } from './prefs.js';
+export { DEFAULT_PREFS, deviceTimeZone, type Prefs, TIME_ZONES, type Theme, type TimeZoneId, getPrefs, resolvedTheme, setPref, timeZoneLabel, usePrefs, ASSISTANT_WIDTH, } from './prefs.js';
 export { KIT, type KitConfig, configureLumen } from './kit-config.js';
 export { ConnectionBlock, ErrorLine, IntegrationRow, KeyTestLine, type KeyTestResult, TestBadge, errorText, useClock, } from './integrations.js';
 export { LumenPager } from './pager.js';

package/dist/index.js

@@ -42,7 +42,7 @@ export { GrowthChart, KEY_DATE_KINDS, KeyDateChips, PALETTE, benchColour, keyDat
 export { FoldGroup, NavGroup, SidebarSection, } from './nav.js';
 export { OverviewList, OverviewPage, ToneDot, } from './overview.js';
 export { IconButton, Page, PageBody, PageHeader, } from './page.js';
-export { DEFAULT_PREFS, TIME_ZONES, getPrefs, resolvedTheme, setPref, timeZoneLabel, usePrefs, ASSISTANT_WIDTH, } from './prefs.js';
+export { DEFAULT_PREFS, deviceTimeZone, TIME_ZONES, getPrefs, resolvedTheme, setPref, timeZoneLabel, usePrefs, ASSISTANT_WIDTH, } from './prefs.js';
 export { KIT, configureLumen } from './kit-config.js';
 export { ConnectionBlock, ErrorLine, IntegrationRow, KeyTestLine, TestBadge, errorText, useClock, } from './integrations.js';
 export { LumenPager } from './pager.js';

package/dist/kit-config.d.ts

@@ -1,3 +1,4 @@
+import type { Prefs } from './prefs.js';
 export interface KitConfig {
     /** The cookie that keeps each person's display preferences. */
     prefsCookie: string;
@@ -5,6 +6,8 @@ export interface KitConfig {
     cookieDomain?: (host: string) => string | undefined;
     /** What a market widget says where the app has no live feed. */
     marketOff: string;
+    /** The app's own defaults for preferences a person has not set (theme, time zone, ...). */
+    defaultPrefs?: Partial<Prefs>;
 }
 export declare const KIT: KitConfig;
 /** Runs `fn` after each `configureLumen` (preferences read again from the app's cookie). */

package/dist/prefs.d.ts

@@ -62,6 +62,8 @@ export declare const ASSISTANT_WIDTH: {
 };
 /** Eastern by default, as an app's zone picker had it (the market's own zone). */
 export declare const DEFAULT_PREFS: Prefs;
+/** The device's own zone when the picker lists it (`America/Los_Angeles`), else undefined. */
+export declare function deviceTimeZone(): TimeZoneId | undefined;
 /** The theme on screen: `system` follows the device. */
 export declare const resolvedTheme: (p?: Prefs) => 'light' | 'dark';
 export declare function setPref<K extends keyof Prefs>(key: K, value: Prefs[K]): void;

package/dist/prefs.js

@@ -38,6 +38,13 @@ export const DEFAULT_PREFS = {
     hideAmounts: false,
     observability: false,
 };
+/** The kit's defaults with the app's own (`configureLumen` `defaultPrefs`) over them. */
+const defaults = () => ({ ...DEFAULT_PREFS, ...KIT.defaultPrefs });
+/** The device's own zone when the picker lists it (`America/Los_Angeles`), else undefined. */
+export function deviceTimeZone() {
+    const zone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    return TIME_ZONES.find((z) => z.id === zone)?.id;
+}
 const YEAR = 60 * 60 * 24 * 365;
 const listeners = new Set();
 /** The app's shared cookie domain (`configureLumen`); host-only when it names none. */
@@ -46,26 +53,27 @@ function cookieDomain() {
     return domain ? `; domain=${domain}` : '';
 }
 function read() {
+    const d = defaults();
     try {
         const raw = document.cookie
             .split('; ')
             .find((c) => c.startsWith(`${KIT.prefsCookie}=`))
             ?.slice(KIT.prefsCookie.length + 1);
         if (!raw)
-            return DEFAULT_PREFS;
+            return d;
         const v = JSON.parse(decodeURIComponent(raw));
         return {
-            theme: THEMES.includes(v.theme) ? v.theme : DEFAULT_PREFS.theme,
-            glass: v.glass === true,
-            font: FONTS.find((f) => f.id === v.font)?.id ?? DEFAULT_PREFS.font,
-            fontSize: FONT_SIZES.find((f) => f.id === v.fontSize)?.id ?? DEFAULT_PREFS.fontSize,
-            timeZone: TIME_ZONES.find((z) => z.id === v.timeZone)?.id ?? DEFAULT_PREFS.timeZone,
-            hideAmounts: v.hideAmounts === true,
-            observability: v.observability === true,
+            theme: THEMES.includes(v.theme) ? v.theme : d.theme,
+            glass: typeof v.glass === 'boolean' ? v.glass : d.glass,
+            font: FONTS.find((f) => f.id === v.font)?.id ?? d.font,
+            fontSize: FONT_SIZES.find((f) => f.id === v.fontSize)?.id ?? d.fontSize,
+            timeZone: TIME_ZONES.find((z) => z.id === v.timeZone)?.id ?? d.timeZone,
+            hideAmounts: typeof v.hideAmounts === 'boolean' ? v.hideAmounts : d.hideAmounts,
+            observability: typeof v.observability === 'boolean' ? v.observability : d.observability,
         };
     }
     catch {
-        return DEFAULT_PREFS;
+        return d;
     }
 }
 let state = typeof document === 'undefined' ? DEFAULT_PREFS : read();

package/dist/schedules.js

@@ -11,7 +11,7 @@ import { LumenConfirm } from './confirm.js';
 import { useIsMobile } from './hooks/use-mobile.js';
 import { LumenSelector } from './lumen-selector.js';
 import { IconButton } from './page.js';
-import { usePrefs } from './prefs.js';
+import { timeZoneLabel, usePrefs } from './prefs.js';
 import { useShell } from './shell.js';
 import { Badge } from './ui/badge.js';
 import { Button } from './ui/button.js';
@@ -183,10 +183,10 @@ export function SchedulesSection({ schedules, error, onSave, onRun, onRuns, rece
         return _jsx("p", { className: "text-sm text-loss", children: error });
     if (!schedules)
         return _jsx(Skeleton, { className: "h-48 w-full" });
-    return (_jsxs(_Fragment, { children: [isMobile ? (_jsx("div", { className: "grid grid-cols-1 divide-y rounded-lg border", children: schedules.map((s) => (_jsxs("button", { type: "button", className: "grid grid-cols-[1fr_auto] items-center gap-x-3 gap-y-1 p-3 text-left hover:bg-muted/50", onClick: () => setOpen(s.id), children: [_jsx("span", { className: "font-medium", children: s.name }), _jsx(OnSwitch, { s: s, onSave: onSave }), _jsxs("span", { className: "col-span-2 text-xs text-muted-foreground", children: [s.kind === 'daily' ? '' : `Every ${everyText(s.every)} · `, when(s)] }), _jsx("span", { className: "col-span-2 text-xs", children: s.waiting ? _jsx("span", { className: "text-warning", children: s.waiting }) : _jsx(Last, { s: s }) })] }, s.id))) })) : (_jsx("div", { className: "overflow-x-auto overflow-y-hidden rounded-lg border", children: _jsxs(Table, { children: [_jsx(TableHeader, { children: _jsxs(TableRow, { children: [_jsx(TableHead, { className: "w-12", children: "On" }), _jsx(TableHead, { children: "Schedule" }), _jsx(TableHead, { children: "When" }), _jsx(TableHead, { children: "Last run" }), onRuns ? _jsx(TableHead, { className: "w-0" }) : null] }) }), _jsx(TableBody, { children: schedules.map((s) => (_jsxs(TableRow, { className: "cursor-pointer", onClick: () => setOpen(s.id), children: [_jsx(TableCell, { children: _jsx(OnSwitch, { s: s, onSave: onSave }) }), _jsx(TableCell, { className: "font-medium", children: s.name }), _jsxs(TableCell, { className: "max-w-36 truncate text-muted-foreground", children: [s.kind === 'daily' ? '' : `Every ${everyText(s.every)} · `, when(s)] }), _jsx(TableCell, { className: "max-w-48", children: s.waiting ? (_jsx(Badge, { variant: "outline", className: "text-warning", title: s.waiting, children: "Not connected" })) : (_jsx(Last, { s: s, compact: true })) }), onRuns ? (_jsx(TableCell, { children: _jsx(IconButton, { icon: ListIcon, label: `${s.name} runs`, onClick: (e) => {
+    return (_jsxs(_Fragment, { children: [isMobile ? (_jsx("div", { className: "grid grid-cols-1 divide-y rounded-lg border", children: schedules.map((s) => (_jsxs("button", { type: "button", className: "grid grid-cols-[1fr_auto] items-center gap-x-3 gap-y-1 p-3 text-left hover:bg-muted/50", onClick: () => setOpen(s.id), children: [_jsx("span", { className: "font-medium", children: s.name }), _jsx(OnSwitch, { s: s, onSave: onSave }), _jsxs("span", { className: "col-span-2 text-xs text-muted-foreground", children: [s.kind === 'daily' ? '' : `Every ${everyText(s.every)} · `, when(s)] }), _jsx("span", { className: "col-span-2 text-xs", children: s.waiting ? _jsx("span", { className: "text-warning", children: s.waiting }) : _jsx(Last, { s: s }) })] }, s.id))) })) : (_jsx("div", { className: "overflow-x-auto overflow-y-hidden rounded-lg border", children: _jsxs(Table, { children: [_jsx(TableHeader, { children: _jsxs(TableRow, { children: [_jsx(TableHead, { className: "w-12", children: "On" }), _jsx(TableHead, { children: "Schedule" }), _jsx(TableHead, { children: "When" }), _jsx(TableHead, { children: "Last run" }), onRuns ? _jsx(TableHead, { className: "w-0" }) : null] }) }), _jsx(TableBody, { children: schedules.map((s) => (_jsxs(TableRow, { className: "cursor-pointer", onClick: () => setOpen(s.id), children: [_jsx(TableCell, { children: _jsx(OnSwitch, { s: s, onSave: onSave }) }), _jsx(TableCell, { className: "font-medium", children: s.name }), _jsxs(TableCell, { className: "min-w-48 whitespace-normal text-muted-foreground", children: [s.kind === 'daily' ? '' : `Every ${everyText(s.every)} · `, when(s)] }), _jsx(TableCell, { className: "max-w-48", children: s.waiting ? (_jsx(Badge, { variant: "outline", className: "text-warning", title: s.waiting, children: "Not connected" })) : (_jsx(Last, { s: s, compact: true })) }), onRuns ? (_jsx(TableCell, { children: _jsx(IconButton, { icon: ListIcon, label: `${s.name} runs`, onClick: (e) => {
                                                 e.stopPropagation();
                                                 toRuns?.(s.id);
-                                            } }) })) : null] }, s.id))) })] }) })), _jsxs("div", { className: "flex flex-wrap items-center justify-between gap-2", children: [_jsxs("p", { className: "text-xs text-muted-foreground", children: ["Times shown in ", timeZone.replace('_', ' '), ". Each run is a line in Logs."] }), briefs ? (_jsxs(Button, { variant: "outline", size: "sm", onClick: () => setAdding(true), children: [_jsx(PlusIcon, {}), "Brief"] })) : null] }), briefs ? (_jsx(Sheet, { open: adding, onOpenChange: setAdding, children: _jsx(SheetContent, { side: isMobile ? 'bottom' : 'right', className: "gap-4", children: _jsx(NewBrief, { create: async (b, time) => {
+                                            } }) })) : null] }, s.id))) })] }) })), _jsxs("div", { className: "flex flex-wrap items-center justify-between gap-2", children: [_jsxs("p", { className: "text-xs text-muted-foreground", children: ["Last runs shown in ", timeZoneLabel(timeZone), ".", onRuns ? ' Each run is a line in Logs.' : ''] }), briefs ? (_jsxs(Button, { variant: "outline", size: "sm", onClick: () => setAdding(true), children: [_jsx(PlusIcon, {}), "Brief"] })) : null] }), briefs ? (_jsx(Sheet, { open: adding, onOpenChange: setAdding, children: _jsx(SheetContent, { side: isMobile ? 'bottom' : 'right', className: "gap-4", children: _jsx(NewBrief, { create: async (b, time) => {
                             const id = await briefs.create(b);
                             await onSave(id, time);
                             return id;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@columenlabs/lumen-ui",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "description": "Lumen: shared React components (frame, views, widgets, charts, drawers).",
   "license": "MIT",
   "type": "module",
@@ -41,7 +41,7 @@
     "@codemirror/lang-javascript": "6.2.5",
     "@codemirror/lang-json": "6.0.2",
     "@codemirror/lang-sql": "6.10.0",
-    "@columenlabs/lumen-ui-types": "0.1.25",
+    "@columenlabs/lumen-ui-types": "0.1.27",
     "@dnd-kit/core": "6.3.1",
     "@dnd-kit/sortable": "10.0.0",
     "@dnd-kit/utilities": "3.2.2",