@columenlabs/lumen-ui 0.0.0-stage → 0.2.1

package/dist/lumen-view-card.d.ts

@@ -0,0 +1,35 @@
+import { type ViewCard } from '@columenlabs/lumen-ui-types/views';
+import type { RowData } from '@tanstack/react-table';
+import { type ReactNode } from 'react';
+import { type FilterToken } from './lumen-filter.js';
+import type { LumenLoad } from './lumen-source.js';
+import { type CustomViewConfig, type ViewDomain } from './lumen-view.js';
+import { type CardControls } from './lumen-widget.js';
+export interface LumenViewCardProps<T> {
+    /** Its card id on the page (its fold is kept per id); left out, its name. */
+    id?: string;
+    domain: ViewDomain<T>;
+    /** The view's columns, filters and pagination; the Columns picker changes them for this visit. */
+    config: CustomViewConfig;
+    rows: T[];
+    load?: LumenLoad;
+    title?: string;
+    /** Buttons in the card's header before the pager. */
+    tools?: ReactNode;
+    /** A short subtitle after the title (a repo path). */
+    note?: ReactNode;
+    /** Shown in place of the table (an empty state). */
+    state?: ReactNode;
+    /** A row click (pick a version, open a drawer). */
+    onDetails?: (row: T) => void;
+    /** Its place in the layout: the layout's `frame` hands these over. */
+    controls?: CardControls;
+    /** Its saved controls (Edit widget ▸ Controls), on a saved page's table. */
+    shown?: ViewCard['controls'];
+    /** Saves a Columns change; left out, it lasts the visit. */
+    onColumns?: (columns: string[]) => void;
+    /** Chips it shares with the cards of its colour besides its filter's: what a control in its
+     *  header picked (`{key: 'book', value: 'Live'}`), like a code card's `publishes`. */
+    publishes?: FilterToken[];
+}
+export declare function LumenViewCard<T extends RowData>({ id, domain: base, config: saved, rows, load, title, tools, note, state, onDetails, controls, shown: savedControls, onColumns, publishes, }: LumenViewCardProps<T>): import("react").JSX.Element;

package/dist/lumen-view-card.js

@@ -0,0 +1,50 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { controlOn } from '@columenlabs/lumen-ui-types/views';
+import { useEffect, useMemo, useState } from 'react';
+import { useGroup } from './group-button.js';
+import { useJoins } from './joins.js';
+import { LumenTokenizedFilter, filterByTokens, useLumenFilter, } from './lumen-filter.js';
+import { followedBy, followsText, keyFilterFields, useLinks, usePublishLinks, useRowPick, } from './lumen-links.js';
+import { LumenView } from './lumen-view.js';
+import { cardFilterFields } from './lumen-widget.js';
+import { filterFieldsOf } from './view-model.js';
+export function LumenViewCard({ id, domain: base, config: saved, rows, load, title, tools, note, state, onDetails, controls, shown: savedControls, onColumns, publishes, }) {
+    const [config, setConfig] = useState(saved);
+    // A saved layout that changes (an edit, the assistant move) is drawn at once.
+    const savedKey = JSON.stringify(saved);
+    // biome-ignore lint/correctness/useExhaustiveDependencies: keyed on the saved config's content.
+    useEffect(() => setConfig(saved), [savedKey]);
+    // The registry's join fields for the keys the rows carry.
+    const { domain } = useJoins(base, rows, config);
+    const fields = useMemo(() => cardFilterFields(filterFieldsOf(domain.fields, config.filters.fields)), [domain.fields, config.filters.fields]);
+    const filter = useLumenFilter(rows, fields, {
+        text: domain.text,
+        initial: config.filters.default,
+    });
+    const group = useGroup(domain, config);
+    const cardId = id ?? config.name;
+    const links = useLinks();
+    const color = links?.colorOf(cardId) ?? null;
+    const pick = useRowPick(domain, color);
+    const sharedKey = JSON.stringify(publishes ?? []);
+    // biome-ignore lint/correctness/useExhaustiveDependencies: keyed on what its header shares.
+    const published = useMemo(() => [...filter.tokens, ...pick.token, ...(publishes ?? [])], [filter.tokens, pick.token, sharedKey]);
+    usePublishLinks(cardId, published);
+    // What it follows from the page's other cards of its colour, read on any of its fields.
+    const all = useMemo(() => [...cardFilterFields(domain.fields), ...keyFilterFields(domain.keys)], [domain.fields, domain.keys]);
+    const follows = followedBy(links?.follows(cardId) ?? [], all, domain.keys);
+    const followKey = JSON.stringify(follows);
+    // biome-ignore lint/correctness/useExhaustiveDependencies: keyed on what it follows.
+    const shown = useMemo(() => follows.length ? filterByTokens(filter.results, all, follows, domain.text) : filter.results, [filter.results, all, followKey, domain.text]);
+    const link = links && {
+        color,
+        onPick: (c) => links.setColor(cardId, c),
+        follows: followsText(follows),
+        linked: color ? filter.tokens.length : 0,
+    };
+    const on = (k) => controlOn({ kind: 'table', controls: savedControls }, k);
+    return (_jsx(LumenView, { domain: domain, config: config, rows: shown, total: rows.length, groupBy: group.groupField, pivot: group.pivot, subgroup: group.sub, load: load, state: state, onDetails: pick.onTap ?? onDetails, tapped: pick.tapped, title: title ?? config.name, inLayout: true, cardId: cardId, controls: controls, tools: tools, note: note, filter: _jsxs(_Fragment, { children: [on('filter') && (_jsx(LumenTokenizedFilter, { filter: filter, label: `Filter ${config.name}`, className: "min-w-0 flex-1", link: link || undefined })), on('group') && group.button] }), filterCount: filter.tokens.length, link: link || undefined, shown: savedControls, onColumns: (columns) => {
+            setConfig((c) => ({ ...c, columns }));
+            onColumns?.(columns);
+        } }));
+}

package/dist/lumen-view.d.ts

@@ -0,0 +1,172 @@
+import { type CustomViewConfig, type ViewCard, type ViewChip, type ViewFormat } from '@columenlabs/lumen-ui-types/views';
+import { type RowData } from '@tanstack/react-table';
+import { type ReactNode } from 'react';
+import { type LumenLoad } from './lumen-source.js';
+import { type CardControls, type CardLink } from './lumen-widget.js';
+import { type ViewCellValue, type ViewChipTone, type ViewDomain, type ViewField, type ViewSubgroup } from './view-model.js';
+export type { ViewCellValue, ViewChipTone, ViewDomain, ViewField, ViewFieldGroup, ViewSource, } from './view-model.js';
+export { CHIP_TONE, FORMULAS_GROUP, RUN_STATE_TONE } from './view-model.js';
+export { rollUp } from './view-model.js';
+export type { ViewEditorSection } from './view-editor.js';
+/**
+ * Rows that share the domain's merge key, folded into one row each: within each group, or across
+ * every row when nothing is grouped (no duplicate rows in the flat table).
+ */
+export declare function mergeRows<T>(domain: ViewDomain<T>, rows: T[], groupBy: ViewField<T> | null): T[];
+/** A saved view (`@columenlabs/lumen-ui-types/views`); agents write the same shape through MCP. */
+export type { CustomViewConfig };
+/** A value as its field's format reads: tabular figures, a true minus, gain/loss on signed values. */
+export declare function ViewValueCell({ value, format, chip, tone, color, amount, compact, empty, }: {
+    value: ViewCellValue;
+    format: ViewFormat;
+    /** Text shown as a chip (a view's `chips` setting). */
+    chip?: boolean;
+    /** The chip's colour (a field's `tone`). */
+    tone?: ViewChipTone;
+    /** A dot of this colour before text (a field's `color`). */
+    color?: string;
+    /** A holding amount: shown as `•••••` while Hide amounts is on. */
+    amount?: boolean;
+    /** Large numbers in short form: $283.1B, 6.1M. */
+    compact?: boolean;
+    /** What an empty cell says; left out: a dash. */
+    empty?: string;
+}): import("react").JSX.Element;
+export declare const VIEW_SCROLL = "@container h-[calc(100svh-var(--shell-header-height)-var(--shell-status-height)-var(--shell-gutter))] overflow-auto px-[max(var(--shell-gutter),calc((100%-var(--shell-max-width))/2+var(--shell-gutter)))] pb-(--shell-gutter) [--view-w:calc(100cqw-var(--view-sb,0px))]";
+/** The page body around `VIEW_SCROLL`: the scroller draws the side and bottom gutter and max width. */
+export declare const VIEW_PAGE = "max-w-none px-0 pb-0";
+/** The details: a folded row's own rows as a table, then the domain's sections. */
+export declare function DetailsBody<T extends RowData>({ domain, row, columns, chips, }: {
+    domain: ViewDomain<T>;
+    row: T;
+    columns: ViewField<T>[];
+    chips: ViewChip[];
+}): import("react").JSX.Element;
+export interface LumenViewProps<T> {
+    /** The view's domain, its formula columns included (`withViewFields`). */
+    domain: ViewDomain<T>;
+    config: CustomViewConfig;
+    /** The rows the view shows: its page's filter already applied. */
+    rows: T[];
+    /** Every row before the filter, for "12 of 40 rows"; left out: `rows`. */
+    total?: number;
+    /** The grouping the page picked (its Group by switch); null: flat rows. */
+    groupBy?: ViewField<T> | null;
+    /** Shows the view's pivot instead of its rows. */
+    pivot?: boolean;
+    /** What each row opens, by the domain's sub-group key (the page's Group button); null: none,
+     *  left out: the view's saved pick. */
+    subgroup?: string | null;
+    /** The rows' loading state (`useLumenLoad`): the view shows its skeleton, progress bar, ↻, a
+     *  failure with Retry and, with Observability details on, its load time. */
+    load?: LumenLoad;
+    /** Shown in place of the table instead of the rows, e.g. an empty state ("No accounts yet"). */
+    state?: ReactNode;
+    /** The card's title; left out: the view's name. */
+    title?: string;
+    /** Row checkboxes (strategy lab): the checked row keys and their setter; the
+     *  header box checks every shown row. */
+    selection?: {
+        keys: Set<string>;
+        onChange: (keys: Set<string>) => void;
+    };
+    /** A row click: opens the details drawer, or the row's own page. */
+    onDetails?: (row: T) => void;
+    /** Rows picked by a tap (a linked table's row filter): a muted fill, no border. */
+    tapped?: (row: T) => boolean;
+    /** Buttons at the end of a group row's label (pin a group), given its key and rows. */
+    groupActions?: (key: string, rows: T[]) => ReactNode;
+    /** Its place in a LumenLayout: the layout's edit state and the card's ⋯ menu. */
+    controls?: CardControls;
+    /** In a LumenLayout's scroller: the table scrolls with the page, its header pinned. */
+    inLayout?: boolean;
+    /** The card's id on its page (its fold is kept per id); a page's second table passes its own. */
+    cardId?: string;
+    /** Buttons in the card's header before the pager ("+ Add time"). */
+    tools?: ReactNode;
+    /** The view's own filter and Group in its header (the filter is the table's,
+     *  not the page's), and how many tokens it holds. */
+    filter?: ReactNode;
+    filterCount?: number;
+    /** A line under the filter: the card's Link offer. */
+    strip?: ReactNode;
+    /** Its link colour on the layout. */
+    link?: CardLink;
+    /** A short subtitle after the title (a repo path). */
+    note?: ReactNode;
+    /** The Columns picker in the header: turns any of the domain's fields on
+     *  or off and hands back the view's new columns. Left out: no picker. */
+    onColumns?: (keys: string[]) => void;
+    /** The + at the end of the header (Edits in place): Field (the Columns
+     *  picker, at the +), Formula, Your data and Ask the assistant; each left out is not offered. */
+    onAddColumn?: AddColumn;
+    /** The sort shown, when the page holds it (rule C); left out: the view's saved sort. */
+    sort?: CustomViewConfig['sort'];
+    /** Told when a header click changes the sort. */
+    onSort?: (sort: CustomViewConfig['sort']) => void;
+    /** Its controls from its card (Edit widget ▸ Controls); missing keys take the Table defaults. */
+    shown?: ViewCard['controls'];
+}
+/** What the header's + offers. */
+export interface AddColumn {
+    /** Formula: a column computed from the others; `disabled` says why it is not offered here. */
+    formula?: (() => void) | {
+        disabled: string;
+    };
+    /** Your data: a column the person types; `disabled` says why it is not offered here. */
+    yours?: (() => void) | {
+        disabled: string;
+    };
+}
+/**
+ * LumenView (a card of its own): a data
+ * view over one domain, as a card. Its header has the view's name, the row count and pager, its ↻
+ * and ⋯, and its own filter and Group (they narrow this table only); its body
+ * the table (grouped one level, or the pivot) with the loading states.
+ */
+export declare function LumenView<T extends RowData>({ domain, config, rows, total, groupBy, pivot, subgroup, load: sourceLoad, state, title, selection, onDetails, tapped, groupActions, controls, inLayout: inScroller, cardId, tools, filter, filterCount, strip, link, note, onColumns, onAddColumn, sort, onSort, shown, }: LumenViewProps<T>): import("react").JSX.Element;
+/** A field's colour for its header: its topic's source (a broker green, an app brown) where
+ *  the group names one, else its group's (Holding, Symbol, Account, Formulas). */
+export declare function colorOf<T>(domain: ViewDomain<T>, f: ViewField<T> | undefined): string | null;
+/** The plain table LumenView draws, also standalone for lists that are not a whole view; with
+ *  `load` it shows its own skeleton, progress bar and failure. */
+export declare function LumenTable<T extends RowData>({ load, ...props }: LumenTableProps<T> & {
+    load?: LumenLoad;
+}): import("react").JSX.Element;
+export interface LumenTableProps<T> {
+    domain: ViewDomain<T>;
+    /** The fields shown, in order; every field of the domain when left out. */
+    columns?: ViewField<T>[];
+    rows: T[];
+    groupBy?: ViewField<T> | null;
+    chips?: ViewChip[];
+    /** The page a flat table shows; null shows every row. */
+    page?: {
+        index: number;
+        size: number;
+    } | null;
+    /** The view page's own table, which scrolls with the page rather than in its card. */
+    inView?: boolean;
+    /** Text cells wrap so the table fits the width there is, rather than scrolling sideways. */
+    fit?: boolean;
+    onDetails?: (row: T) => void;
+    tapped?: LumenViewProps<T>['tapped'];
+    selection?: LumenViewProps<T>['selection'];
+    groupActions?: LumenViewProps<T>['groupActions'];
+    /** The view's default sort; a header click changes it for the visit. */
+    sort?: CustomViewConfig['sort'];
+    /** Told the sort a header click sets, so a page can hold or save it (rule C). */
+    onSort?: (sort: CustomViewConfig['sort']) => void;
+    /** The + Add column head at the end of the header. */
+    add?: AddColumn & {
+        field?: {
+            domain: ViewDomain<T>;
+            columns: ViewField<T>[];
+            onColumns: (keys: string[]) => void;
+        };
+    };
+    /** Draws the Total row under the rows; the view's `total: false` leaves it out. */
+    total?: boolean;
+    /** What each row opens under it (`subgroupOf`); null: rows open nothing but their panel. */
+    subgroup?: ViewSubgroup<T> | null;
+}