@columenlabs/lumen-ui 0.0.0-stage → 0.2.1

package/dist/lumen-grid.js

@@ -0,0 +1,203 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// LumenGrid: an
+// LumenLayout's cards on a real grid, react-grid-layout underneath. A desktop has 6 columns, a phone
+// 2; rows are 8px. A card is placed at x, y and sized w by h; a card with no h is as tall as what it
+// shows (measured), and cards that start on the same row match the tallest of them. While the layout
+// is edited, cards move by their grip and size from their corner; a card resized keeps its height.
+// Outside Edit layout a full-width table stays out of the grid, so it keeps scrolling sideways with
+// the page while the cards around it stay put.
+import { GRID_BLOCK_ROWS, GRID_COLS, GRID_PHONE_COLS, GRID_ROW_PX, } from '@columenlabs/lumen-ui-types/views';
+import { createContext, useCallback, useContext, useLayoutEffect, useMemo, useRef, useState, } from 'react';
+import { GridLayout, useContainerWidth, verticalCompactor, } from 'react-grid-layout';
+import { cn } from './lib/utils.js';
+import { LumenBoundary } from './lumen-boundary.js';
+/** The gap between cards, the shell's section gap. */
+export const GRID_GAP = 12;
+/** Narrower than this the grid has the phone's 2 columns. */
+const PHONE_BELOW = 720;
+/** A card's height before it is measured. */
+const GUESS = GRID_BLOCK_ROWS * 2;
+/** Inside a grid cell: `fixed` when the cell has a height of its own, so the card fills it. */
+const GridCellContext = createContext(null);
+export const useGridCell = () => useContext(GridCellContext);
+const CARD = '[data-slot=lumen-card]';
+const rowsOf = (px) => Math.max(2, Math.ceil((px + GRID_GAP) / GRID_ROW_PX));
+const byPlace = (a, b) => a.y - b.y || a.x - b.x;
+/** Cards placed where they say and, in order after them, the ones that do not, row by row. */
+function arrange(cards, cols, top) {
+    const out = [];
+    let bottom = top;
+    for (const c of cards)
+        if (c.x !== undefined && c.y !== undefined) {
+            const w = Math.min(c.w, cols);
+            out.push({ i: c.id, x: Math.min(c.x, cols - w), y: top + c.y, w, h: c.h });
+            bottom = Math.max(bottom, top + c.y + c.h);
+        }
+    let x = 0;
+    let row = 0;
+    for (const c of cards) {
+        if (c.x !== undefined && c.y !== undefined)
+            continue;
+        const w = Math.min(c.w, cols);
+        if (x + w > cols) {
+            x = 0;
+            row += 1;
+        }
+        // Rows far apart: compacting pulls each up under the row before it.
+        out.push({ i: c.id, x, y: bottom + row * 10_000, w, h: c.h });
+        x += w;
+    }
+    return out;
+}
+/** The highest row a laid-out set reaches. */
+const bottomOf = (items) => items.reduce((m, it) => Math.max(m, it.y + it.h), 0);
+/**
+ * The grid's layout: the page's lead cards, then the saved ones where they were placed, then the
+ * page's other cards, compacted upward; cards of measured height starting on the same row take the
+ * tallest's height.
+ */
+export function gridLayout(groups, heights, phone) {
+    const cols = phone ? GRID_PHONE_COLS : GRID_COLS;
+    const auto = new Set();
+    const sized = (c) => {
+        const own = phone ? c.phone?.h : c.h;
+        if (own === undefined)
+            auto.add(c.id);
+        const h = own ?? heights[c.id] ?? GUESS;
+        if (!phone)
+            return { id: c.id, w: c.w, h, x: c.x, y: c.y };
+        if (c.phone)
+            return { id: c.id, w: c.phone.w, h, x: c.phone.x, y: c.phone.y };
+        return { id: c.id, w: c.w <= 1 ? 1 : GRID_PHONE_COLS, h };
+    };
+    // A phone with no places of its own keeps the desktop's reading order.
+    const ordered = phone
+        ? groups.map((g) => {
+            if (g.some((c) => c.phone))
+                return g;
+            const at = new Map(gridLayout([g], heights, false).map((it) => [it.i, it]));
+            return [...g].sort((a, b) => {
+                const pa = at.get(a.id);
+                const pb = at.get(b.id);
+                return pa && pb ? byPlace(pa, pb) : 0;
+            });
+        })
+        : groups;
+    let items = [];
+    for (const g of ordered)
+        items = [...items, ...arrange(g.map(sized), cols, bottomOf(items))];
+    // A row settles only once the one above it has, so match heights and compact until nothing moves.
+    let laid = [...verticalCompactor.compact(items, cols)];
+    for (let pass = 0; pass < laid.length; pass++) {
+        const tallest = new Map();
+        for (const it of laid)
+            tallest.set(it.y, Math.max(tallest.get(it.y) ?? 0, it.h));
+        let changed = false;
+        const even = laid.map((it) => {
+            const h = auto.has(it.i) ? (tallest.get(it.y) ?? it.h) : it.h;
+            if (h !== it.h)
+                changed = true;
+            return h === it.h ? it : { ...it, h };
+        });
+        if (!changed)
+            break;
+        laid = [...verticalCompactor.compact(even, cols)];
+    }
+    return laid.sort(byPlace);
+}
+/** A cell measures what it draws when it has no height of its own (a frame: its parts). */
+function Cell({ id, fixed, report, children, }) {
+    const ref = useRef(null);
+    useLayoutEffect(() => {
+        const cell = ref.current;
+        if (fixed || !cell)
+            return;
+        const measure = () => {
+            const el = cell.firstElementChild;
+            if (!el)
+                return report(id, 0);
+            // A card fills its cell (through a wrapper too), so its height is its parts': header,
+            // filter, body and footer, plus whatever else the wrapper holds.
+            const card = el.matches(CARD) ? el : el.querySelector(`:scope > ${CARD}`);
+            const px = card
+                ? [...card.children].reduce((s, c) => s + c.offsetHeight, 0) +
+                    (card.offsetHeight - card.clientHeight) +
+                    (el.offsetHeight - card.offsetHeight)
+                : el.offsetHeight;
+            report(id, px);
+        };
+        measure();
+        const ro = new ResizeObserver(measure);
+        const el = cell.firstElementChild;
+        const card = el?.matches(CARD) ? el : el?.querySelector(`:scope > ${CARD}`);
+        if (el)
+            ro.observe(el);
+        if (card)
+            for (const c of card.children)
+                ro.observe(c);
+        return () => ro.disconnect();
+    });
+    const value = useMemo(() => ({ fixed }), [fixed]);
+    return (_jsx(GridCellContext.Provider, { value: value, children: _jsx("div", { ref: ref, className: "h-full [&>*:has(>[data-slot=lumen-card])]:h-full", style: { paddingBottom: GRID_GAP }, children: children }) }));
+}
+const gridConfig = (phone) => ({
+    cols: phone ? GRID_PHONE_COLS : GRID_COLS,
+    rowHeight: GRID_ROW_PX,
+    margin: [GRID_GAP, 0],
+    containerPadding: [0, 0],
+});
+/** The page's cards on the grid; `onPlace` makes them movable and sizable (Edit layout). */
+export function LumenGrid({ lead = [], cards, tail = [], editing, onPlace, }) {
+    const { width, containerRef, mounted } = useContainerWidth({ measureBeforeMount: true });
+    const phone = width < PHONE_BELOW;
+    const [heights, setHeights] = useState({});
+    const report = useCallback((id, px) => setHeights((h) => {
+        const r = rowsOf(px);
+        return h[id] === r ? h : { ...h, [id]: r };
+    }), []);
+    const all = [...lead, ...cards, ...tail];
+    const byId = new Map(all.map((c) => [c.id, c]));
+    const layout = gridLayout([lead, cards, tail], heights, phone);
+    const own = (c) => (phone ? c.phone?.h : c.h);
+    const cell = (c) => (_jsx("div", { "data-locked": c.locked || undefined, children: _jsx(Cell, { id: c.id, fixed: own(c) !== undefined, report: report, children: _jsx(LumenBoundary, { where: c.id, children: c.node }) }) }, c.id));
+    const measure = (_jsx("div", { ref: containerRef, "aria-hidden": true, className: "sticky left-0 h-0 w-(--view-w) -mb-3" }));
+    if (editing) {
+        const commit = (l, resized) => onPlace?.([...l]
+            .filter((it) => !byId.get(it.i)?.locked)
+            .sort(byPlace)
+            .map((it) => {
+            const c = byId.get(it.i);
+            const h = it.i === resized ? it.h : c && own(c);
+            return { id: it.i, x: it.x, y: it.y, w: it.w, ...(h === undefined ? {} : { h }) };
+        }), phone);
+        return (_jsxs(_Fragment, { children: [measure, _jsx("div", { className: "sticky left-0 w-(--view-w)", style: { marginBottom: -GRID_GAP }, children: mounted && (_jsx(GridLayout, { width: width, layout: layout.map((it) => byId.get(it.i)?.locked ? { ...it, isDraggable: false, isResizable: false } : it), gridConfig: gridConfig(phone), dragConfig: { handle: '.lumen-drag', threshold: 4 }, resizeConfig: { enabled: true, handles: ['se'] }, compactor: verticalCompactor, className: "lumen-grid lumen-grid-edit", onDragStop: (l) => commit(l), onResizeStop: (l, _o, n) => commit(l, n?.i), children: layout.flatMap((it) => {
+                            const c = byId.get(it.i);
+                            return c ? [cell(c)] : [];
+                        }) })) })] }));
+    }
+    // Outside Edit layout: runs of cards on the grid, with each full-width table between them.
+    const parts = [];
+    for (const it of layout) {
+        const c = byId.get(it.i);
+        if (!c)
+            continue;
+        const last = parts[parts.length - 1];
+        if (c.wide)
+            parts.push(c);
+        else if (Array.isArray(last))
+            last.push(it);
+        else
+            parts.push([it]);
+    }
+    return (_jsxs(_Fragment, { children: [measure, mounted &&
+                parts.map((p) => Array.isArray(p) ? (_jsx(GridRun, { items: p, phone: phone, width: width, cell: (id) => {
+                        const c = byId.get(id);
+                        return c ? cell(c) : null;
+                    } }, p.map((it) => it.i).join())) : (_jsx("div", { className: "not-has-[table]:sticky not-has-[table]:left-0 not-has-[table]:w-(--view-w)", children: p.node }, p.id)))] }));
+}
+/** Cards between two full-width tables: their own grid, from the row the first starts on. */
+function GridRun({ items, phone, width, cell, }) {
+    const top = Math.min(...items.map((it) => it.y));
+    const layout = items.map((it) => ({ ...it, y: it.y - top, static: true }));
+    return (_jsx("div", { className: cn('sticky left-0 w-(--view-w)'), style: { marginBottom: -GRID_GAP }, children: _jsx(GridLayout, { width: width, layout: layout, gridConfig: gridConfig(phone), dragConfig: { enabled: false }, resizeConfig: { enabled: false }, compactor: verticalCompactor, className: "lumen-grid", children: items.map((it) => cell(it.i)) }) }));
+}

package/dist/lumen-layout.d.ts

@@ -0,0 +1,150 @@
+import { type CustomViewConfig } from '@columenlabs/lumen-ui-types/views';
+import type { RowData } from '@tanstack/react-table';
+import { type LucideIcon } from 'lucide-react';
+import { type ReactElement, type ReactNode } from 'react';
+import { type FilterToken } from './lumen-filter.js';
+import { type LinkColor } from './lumen-links.js';
+import { type LumenLoad } from './lumen-source.js';
+import { type LumenViewProps } from './lumen-view.js';
+import { type CardControls, type CardLink } from './lumen-widget.js';
+import { type Crumb } from './page.js';
+import { type ViewEditorSection } from './view-editor.js';
+import { type ViewDomain } from './view-model.js';
+/** A card a page builds in code, after the saved view's cards: a view of other data, a list. */
+export interface LumenLayoutCard {
+    id: string;
+    title: string;
+    icon?: LucideIcon;
+    /** Tables (and grids) take the full width and show a progress bar; widgets a skeleton.
+     *  `own`: a body that draws its own frame (LumenCoverageMap, LumenCoverageCalendarMap). */
+    kind?: 'table' | 'widget' | 'own';
+    /** Columns of 6 it spans (left out: all 6), and rows of 8px it is tall (left out: as it draws). */
+    w?: number;
+    h?: number;
+    /** Its source's loading state: its ↻, states and load time. */
+    load?: LumenLoad;
+    rows?: number;
+    /** Buttons or links in the card's header, before its ↻ ("All jobs"). */
+    tools?: ReactNode;
+    /** ⓘ How to read: a few lines on what the card shows and what to look for. */
+    help?: ReactNode;
+    /** What ✦ Ask the assistant adds to its question (the record to read); false: no ✦ on this card. */
+    assistant?: string | false;
+    /** Every card carries the link square: left out, the page keeps its colour;
+     *  false for a form (setup, what-if), which has no data to link; a CardLink to drive it by hand. */
+    link?: CardLink | false;
+    /** Its colour when the page opens (left out: none). */
+    color?: LinkColor;
+    /** Chips it shares with the cards of its colour: what a control in its header or a tap in its
+     *  body picked (`{key: 'book', value: 'Live'}`). */
+    publishes?: FilterToken[];
+    /** The keys it narrows on: of its colour's chips it follows these, says them after its title
+     *  and hands them to `children` when that is a function. */
+    reads?: string[];
+    /** Shown while the first load runs (a row of tile placeholders). */
+    skeleton?: ReactNode;
+    children?: ReactNode | ((follows: FilterToken[]) => ReactNode);
+    /** An `own` card that takes its place in a saved view's layout (LumenViewCard): drawn with the
+     *  layout's controls and the width the layout keeps for it. Its id must be a field-style key
+     *  (lowercase, digits, _) that no card of the view uses. */
+    frame?: (f: {
+        controls?: CardControls;
+    }) => ReactNode;
+}
+interface PageProps {
+    crumbs: Crumb[];
+    actions?: ReactNode;
+    /** A short status line beside the breadcrumb ("Updated 18:22", a warnings badge). */
+    meta?: ReactNode;
+    status?: ReactNode;
+    /** Above the cards: tabs or a lead the app shows with this page. */
+    intro?: ReactNode;
+    /** The page's own cards, after the saved view's. One with a `frame` joins the saved layout as a
+     *  `page` card: moved and sized like the rest, last until it is placed. */
+    cards?: LumenLayoutCard[];
+    /** The page's own cards before the saved view's (a chart over the list it draws from). */
+    lead?: LumenLayoutCard[];
+    /** Cards take the page's width and wide ones scroll inside themselves (coverage pages). */
+    fit?: boolean;
+}
+/** A saved view on the page: its domain, config and rows. */
+export interface LumenLayoutViewProps<T> {
+    domain: ViewDomain<T>;
+    config: CustomViewConfig;
+    rows: T[];
+    /** Saves an edited view; without it the page has no Edit button. */
+    onConfigChange?: (config: CustomViewConfig) => void;
+    /**
+     * Whether the page's layout can be edited (every page is a saved view, with
+     * this flag set in code for now). False locks it: no Edit, no ＋ Widget, no column changes, even
+     * with `onConfigChange` given. Left out: editable where `onConfigChange` is.
+     */
+    editable?: boolean;
+    /** An app's own section in the Edit dialog (an explorer view's columns). */
+    editor?: ViewEditorSection;
+    /** Duplicate and Delete, offered in the Edit dialog's More section. */
+    onDuplicate?: () => void;
+    onDelete?: () => void;
+    /** A built-in page the person changed (`useAppView`): Edit layout offers Reset to default. */
+    onReset?: () => void;
+    /** The rows' loading state (`useLumenLoad` over the queries the rows come from): every view and
+     *  widget shows its ↻, skeleton, error and load time from it, so it is required. */
+    load: LumenLoad;
+    /** Shown in place of the table instead of the rows, e.g. an empty state ("No accounts yet"). */
+    state?: ReactNode;
+    /** Draws one of the domain's tiles over the view's rows (not the table's filter); the
+     *  view's `tiles` pick which, in order. */
+    tile?: (key: string, rows: T[]) => ReactNode;
+    /** The details drawer title for a row. */
+    rowTitle?: (row: T) => string;
+    /** The saved view's id, shown in the Edit dialog to copy for an MCP call. */
+    viewId?: string;
+    /** Told the rows the view shows after its filters, every page, whenever they change, so an app
+     *  loads live data for those rows only. */
+    onShownRows?: (rows: T[]) => void;
+    /** Told every row the page's Summaries draw, so an app loads live data for those too
+     * : a Summary not linked to the table covers rows the table hides. */
+    onSummaryRows?: (rows: T[]) => void;
+    selection?: LumenViewProps<T>['selection'];
+    /** A row click opens it (a page of its own) instead of the details drawer. */
+    onOpen?: (row: T) => void;
+    /** The `rowLink` value tapped when the page opens, so linked cards start narrowed to one row
+     *  (a playbook's Results open on its Default variant). */
+    rowPick?: string;
+    groupActions?: LumenViewProps<T>['groupActions'];
+    /** Told the filter's tokens whenever they change, so an app can load rows for what they pick
+     *  (the Symbols view's `in` filter). */
+    onTokens?: (tokens: FilterToken[]) => void;
+    /** Buttons in the view card's header ("+ Add time"). */
+    viewTools?: ReactNode;
+    /** False leaves Field out of the header's + Add column (a table whose columns are fixed, a
+     *  Tune's tries); otherwise every editable view offers the Columns picker there. */
+    columnPicker?: boolean;
+    /** No filter box (a short list, e.g. a playbook's variants). */
+    hideFilter?: boolean;
+    /**
+     * How the person's chips, sort and grouping save (rule C, by surface):
+     * `document` (a saved view, the default) holds them for the visit and shows Changed with Save
+     * view and Revert; `sheet` (a workspace tab) saves every change at once through
+     * `onConfigChange`, like a cell in a sheet.
+     */
+    save?: 'sheet' | 'document';
+}
+export type LumenLayoutProps<T> = PageProps & (LumenLayoutViewProps<T> | {
+    domain?: undefined;
+    config?: undefined;
+    rows?: undefined;
+});
+/** A page of cards: a saved view's (its filter, tiles, view and widgets) and the page's own. */
+export declare function LumenLayout<T extends RowData>(props: PageProps & LumenLayoutViewProps<T>): ReactElement;
+/** A page of cards built in code only. */
+export declare function LumenLayout(props: PageProps): ReactElement;
+/** The keys a code card over a domain's rows reads (its `reads`). */
+export declare const domainKeys: (domain: {
+    fields: {
+        key: string;
+    }[];
+}) => string[];
+/** A code card's rows narrowed by the chips it follows, read on the domain's fields. */
+export declare function followRows<T>(domain: ViewDomain<T>, rows: T[], follows: FilterToken[]): T[];
+export {};