@columenlabs/lumen-ui 0.1.54 → 0.1.56

package/README.md

@@ -75,10 +75,13 @@ Every export, its props and an example are on the [docs](https://lumen.columenla
 - 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 page's header numbers are metric cards: `TileRow` of `Tile` (or `TileToggleGroup` when they pick what the page shows), with `fill` so they share the row, each with `spark` set to its daily history where it has one. Don't build a card of your own for this.
+- Column widths: the first column (a row's name) grows only to `--lead-col-max` (18rem, theme.css); past it the cell truncates on one line and a plain text value shows in full on hover (a rendered cell brings its own hover card). Cap any other column with the field's `maxWidth` (`'12rem'`), or lift the cap with `maxWidth: false`. In a rendered name cell, put the name in a `truncate` span so the ellipsis lands on it, not on a chip after it.
+- Column alignment is the table's, not the cell's. Text left, numbers right, and a number column has one right edge for its header, values, dashes and Total. `UnitValue` puts the unit in a fixed slot after the number (`--unit-slot`, 2rem) and its status dot just left of the number. In a LumenView table the first `UnitValue` drawn in a column marks it (`data-units` on every cell of that column, through the `UnitColumns` context and the cell's `data-col`); theme.css then widens that column's right gutter by the slot and hangs each unit in it. So a plain `—`, `Free` or `$0.21` an app draws in the same column sits on the digits' edge, and the header sits over the digits. Don't hand-place units, dots or padding to line a column up; if a column is off, draw its numbers through `UnitValue`. Outside a LumenView table (a hover card, a tile) `UnitValue` keeps its slot inline.
 - A metered column (use against an allowance) shows one number per cell with `UnitValue` (right-aligned number, fixed muted unit slot, status dot), never `value [pct]`. Offer both readings through the field's `showAs` (Amount / % of allowance, picked per column in Edit view, saved as `shows`); default amounts for sizes (storage) and shares for capped counts. Put the other reading, the allowance and the cost formula in a hover card. Totals use `rollRender`: sum amounts with their unit; a share is the rows' total over their allowance, never a sum of percents.
 - A floating bulk-action bar over a table's selection: Apply clears the selection and the bar goes away; the toast's Undo restores the change, not the selection. Cancel keeps the selection.
 - Bars in a column line up: use `ShareMeter` (fixed track, fixed right-aligned number), never a bar sized by its label.
 - Meter levels are the kit's, not the app's: a share of a cap reads `ok` (grey) under 75%, `watch` (amber) from 75%, `alert` (red) from 90%. `ShareMeter` takes its colour from the share unless you pass `color`; `UnitValue share={0.8}` tints its number and dot the same way; usage progress cards follow the same levels. For any other mark (a dot, a chip, a "nearest cap" cell) call `meterLevel(share)` and colour it with `METER_LEVEL_COLOR` or `meterValueTone(share)`. Override per app with `configureLumen({ meterLevels: { watch: 0.8 } })` (each level can move alone) or per meter with `levels={{ watch: 0.5 }}`. Don't hand-roll `share >= 0.75` checks.
+- Pace (time to a cap at the recent rate) is the kit's: `burnRate(samples, { per, gauge })` over the window's complete samples (hourly, or daily for `7d`), then `timeToCap(rate, used, cap, resetInHours)`. A lone sample above 3× the window's median counts as 3× the median (`spikes` says how many); a run of hot samples counts in full. Show it with `TimeToCap` (`in 2h 05m`, `At cap`, `Resets first`; `short` on a phone), coloured by the meter level of where the meter lands at reset, and pick the window with `PaceWindowPicker` (6h, 12h, 24h, 7d) in the page header; `usePaceWindow()` reads the same choice everywhere, kept in the viewer's browser (`setDefaultPaceWindow` sets the app's default). Don't hand-roll ETAs or a window toggle.
 - Table rows are one line. A cell shows one value (with a small bar or tag at most); anything more (other metrics, the allowance, a breakdown) goes in a hover tooltip, never in stacked text or sub-rows.
 - Chart colours are theme tokens (`var(--chart-1)`, `useChartTokens()`), never hex picked for one theme; `LumenEChart` resolves `var(--…)` in its option so sparklines read in light and dark.
 - "No label" filters come built in: `LumenTokenizedFilter` pins a "No <field>" row on any text field where some rows have no value (an `empty` token); don't add your own toggle for it.

package/dist/index.d.ts

@@ -24,6 +24,8 @@ export { RankedBars, StackedBars, StackedColumns } from './lumen-widget-charts.j
 export { ShareMeter } from './share-meter.js';
 export { METER_LEVEL_COLOR, meterLevel, meterValueTone } from './meter-level.js';
 export { UnitValue } from './unit-value.js';
+export { type BurnRate, burnRate, durationText, PACE_WINDOWS, type Pace, type PaceWindow, paceHours, setDefaultPaceWindow, timeToCap, usePaceWindow, } from './pace.js';
+export { PaceWindowPicker, paceText, TimeToCap } from './time-to-cap.js';
 export { COVERAGE_LEVELS, CoverageCell, type CoverageJobState, type CoverageLevel, CoverageLegend, coverageClass, coverageLabel, coverageLevel, } from './coverage-cells.js';
 export { type CoverageBlock, type CoverageData, type CoverageFact, type CoveragePick, type CoverageRow, type CoverageSummary, LumenCoverageMap, type LumenCoverageMapProps, blockName, blockOf, } from './coverage-map.js';
 export { type CalendarFact, LumenCoverageCalendarMap, type LumenCoverageCalendarMapProps, } from './coverage-calendar-map.js';

package/dist/index.js

@@ -31,6 +31,8 @@ export { RankedBars, StackedBars, StackedColumns } from './lumen-widget-charts.j
 export { ShareMeter } from './share-meter.js';
 export { METER_LEVEL_COLOR, meterLevel, meterValueTone } from './meter-level.js';
 export { UnitValue } from './unit-value.js';
+export { burnRate, durationText, PACE_WINDOWS, paceHours, setDefaultPaceWindow, timeToCap, usePaceWindow, } from './pace.js';
+export { PaceWindowPicker, paceText, TimeToCap } from './time-to-cap.js';
 export { COVERAGE_LEVELS, CoverageCell, CoverageLegend, coverageClass, coverageLabel, coverageLevel, } from './coverage-cells.js';
 export { LumenCoverageMap, blockName, blockOf, } from './coverage-map.js';
 export { LumenCoverageCalendarMap, } from './coverage-calendar-map.js';

package/dist/lumen-view.js

@@ -42,6 +42,7 @@ import { Skeleton } from './ui/skeleton.js';
 import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from './ui/table.js';
 import { ToggleGroup, ToggleGroupItem } from './ui/toggle-group.js';
 import { Tooltip, TooltipContent, TooltipTrigger } from './ui/tooltip.js';
+import { UnitColumns } from './unit-value.js';
 import { EditCell, EditInputCell, EditManyCell } from './view-edit-cell.js';
 import { ViewEditDialog } from './view-editor.js';
 import { fieldOptions } from './view-formulas.js';
@@ -343,6 +344,27 @@ const alignOf = (format) => (format === 'text' ? 'text-left' : 'text-right');
 /** An ISO date, alone or with a time after it: `2026-10-14`, `2026-10-14 16:17`. */
 const isDateText = (v) => typeof v === 'string' && v.length <= 25 && /^\d{4}-\d{2}-\d{2}(?:$|[ T])/.test(v);
 const colOf = (f) => cn(alignOf(f?.format ?? 'text'), f?.hideOnPhone && 'max-md:hidden');
+/**
+ * A column's cell props: its classes, its key (`data-col`), and `data-units` once a `UnitValue`
+ * has drawn in it. Every cell of such a column (header, dash, Total) then right-aligns on the
+ * numbers' edge while the units hang in the gutter (theme.css), so one column has one edge.
+ */
+const colPropsOf = (units) => (f, ...more) => ({
+    className: cn(colOf(f), ...more),
+    'data-col': f?.key,
+    'data-units': f && units.has(f.key) ? '' : undefined,
+});
+/**
+ * A column's widest cell (`maxWidth`): the first column defaults to `--lead-col-max` (18rem in
+ * theme.css), so one long name never pushes the other columns off screen; `false` lifts it.
+ */
+const capOf = (f, i) => f.maxWidth === false ? undefined : (f.maxWidth ?? (i === 0 ? 'var(--lead-col-max)' : undefined));
+/** Holds a cell to its column's cap on one line: text past it ends in an ellipsis. */
+function CappedCell({ max, title, children, }) {
+    if (!max)
+        return children;
+    return (_jsx("div", { className: "flex min-w-0 *:min-w-0 *:max-w-full *:truncate", style: { maxWidth: max }, title: title, children: children }));
+}
 /** The flat or grouped table: sortable headers, a Total row, group rows that collapse. */
 // Sorting, and paging of flat tables (the page is LumenView's, set right of the row count).
 const SORTING = tableFeatures({
@@ -384,6 +406,10 @@ function LumenTableRows({ domain, columns = domain.fields, rows, groupBy = null,
         pageSize: paging ? page.size : Math.max(rows.length, 1),
     };
     // Groups whose state differs from where they start: open, or past OPEN_ALL rows only the first.
+    // Columns a UnitValue has drawn in (`UnitColumns`): their cells share the numbers' edge.
+    const [units, setUnits] = useState(() => new Set());
+    const markUnits = useCallback((key) => setUnits((s) => (s.has(key) ? s : new Set(s).add(key))), []);
+    const col = colPropsOf(units);
     const [flipped, setFlipped] = useState(new Set());
     const [more, setMore] = useState(new Map());
     // The grouped field is the group row's label, so its column hides.
@@ -475,12 +501,13 @@ function LumenTableRows({ domain, columns = domain.fields, rows, groupBy = null,
             const { shown: now, cellOf, inline, chips, computed } = latest.current;
             const field = now[i] ?? f;
             const chip = chips.some((c) => c.key === field.key);
-            return i === 0 && inline.length ? (_jsx(FirstCell, { value: cellOf(field, row.original, chip), chips: inline.flatMap((x) => {
-                    const v = computed.value(x, row.original);
-                    if (!x.edit && (v === null || v === ''))
-                        return [];
-                    return [{ key: x.key, node: cellOf(x, row.original, true) }];
-                }) })) : (cellOf(field, row.original, chip));
+            const v = computed.value(field, row.original);
+            return (_jsx(CappedCell, { max: capOf(field, i), title: !field.render && typeof v === 'string' ? v : undefined, children: i === 0 && inline.length ? (_jsx(FirstCell, { value: cellOf(field, row.original, chip), chips: inline.flatMap((x) => {
+                        const v = computed.value(x, row.original);
+                        if (!x.edit && (v === null || v === ''))
+                            return [];
+                        return [{ key: x.key, node: cellOf(x, row.original, true) }];
+                    }) })) : (cellOf(field, row.original, chip)) }));
         },
     })), [shownKeys, inlineOn, serverSorts?.join(',')]);
     const table = useTable({
@@ -560,7 +587,7 @@ function LumenTableRows({ domain, columns = domain.fields, rows, groupBy = null,
     // drawn; spanning the hidden ones too pushed the group's totals right of their headers.
     const leadSpan = Math.max(1, lead - (isMobile ? shown.slice(0, lead).filter((f) => f.hideOnPhone).length : 0));
     const rollCell = (f, members) => rollsUp(f) && f.rollRender ? (f.rollRender(members)) : rollsUp(f) ? (_jsx(ViewValueCell, { value: computed.roll(f, members), format: f.aggregate && isCountAgg(f.aggregate) ? 'rounded' : f.format, amount: f.aggregate !== 'count' && f.amount, compact: f.compact })) : null;
-    const rollCells = (members) => shown.map((f) => (_jsx(TableCell, { className: colOf(f), children: rollCell(f, members) }, f.key)));
+    const rollCells = (members) => shown.map((f) => (_jsx(TableCell, { ...col(f), children: rollCell(f, members) }, f.key)));
     // A row's chevron opens one level under it, closed by default: its panel, else the view's
     // sub-group ("Each row opens"; None opens nothing).
     const partsOf = (row) => (domain.panel ? [] : (subgroup?.rows?.(row) ?? []));
@@ -577,9 +604,9 @@ function LumenTableRows({ domain, columns = domain.fields, rows, groupBy = null,
                 return n;
             });
         }, children: _jsx(ChevronRightIcon, { className: cn('transition-transform', openParts.has(k) && 'rotate-90') }) }));
-    const partRow = (p, name) => (_jsxs(TableRow, { className: cn('bg-muted/30 text-muted-foreground hover:bg-muted/40', onDetails && 'cursor-pointer'), onClick: onDetails ? () => onDetails(p) : undefined, children: [selection && _jsx(TableCell, {}), shown.map((f, i) => (_jsx(TableCell, { className: cn(colOf(f), i === 0 && 'pl-12'), children: i === 0 ? (_jsxs("span", { className: "flex items-center gap-2", children: [_jsx(CornerDownRightIcon, { className: "size-3.5 shrink-0" }), name
-                            ? name(p)
-                            : cellOf(f, p, chips.some((c) => c.key === f.key))] })) : (cellOf(f, p, chips.some((c) => c.key === f.key))) }, f.key)))] }, `part:${keyOf(p)}`));
+    const partRow = (p, name) => (_jsxs(TableRow, { className: cn('bg-muted/30 text-muted-foreground hover:bg-muted/40', onDetails && 'cursor-pointer'), onClick: onDetails ? () => onDetails(p) : undefined, children: [selection && _jsx(TableCell, {}), shown.map((f, i) => (_jsx(TableCell, { ...col(f, i === 0 && 'pl-12'), children: i === 0 ? (_jsxs("span", { className: "flex items-center gap-2", children: [_jsx(CornerDownRightIcon, { className: "size-3.5 shrink-0" }), _jsx(CappedCell, { max: capOf(f, 0), children: name
+                                ? name(p)
+                                : cellOf(f, p, chips.some((c) => c.key === f.key)) })] })) : (cellOf(f, p, chips.some((c) => c.key === f.key))) }, f.key)))] }, `part:${keyOf(p)}`));
     // The whole row opens the details drawer.
     const dataRow = (r) => (_jsxs(Fragment, { children: [_jsxs(TableRow, { "data-row": domain.rowKey(r.original), "data-state": tapped?.(r.original) ? 'selected' : undefined, className: cn('group/row', onDetails && 'cursor-pointer'), tabIndex: onDetails ? 0 : undefined, onClick: onDetails ? () => onDetails(r.original) : undefined, onKeyDown: onDetails
                     ? (e) => {
@@ -590,14 +617,14 @@ function LumenTableRows({ domain, columns = domain.fields, rows, groupBy = null,
                             onDetails(r.original);
                         }
                     }
-                    : undefined, children: [selectCell(keyOf(r.original), keyOf(r.original)), r.getAllCells().map((c, i) => (_jsx(TableCell, { className: cn(colOf(shown[i]), groupBy && i === 0 && 'pl-8'), style: { background: shown[i]?.tint?.(r.original) }, children: i === 0 && nests ? (_jsxs("span", { className: "flex items-center gap-1", children: [opens(r.original) ? (chevron(keyOf(r.original), openLabel())) : (_jsx("span", { className: "-ml-1 size-6 shrink-0" })), flexRender(c.column.columnDef.cell, c.getContext())] })) : (flexRender(c.column.columnDef.cell, c.getContext())) }, c.id)))] }, domain.rowKey(r.original)), openParts.has(keyOf(r.original)) &&
+                    : undefined, children: [selectCell(keyOf(r.original), keyOf(r.original)), r.getAllCells().map((c, i) => (_jsx(TableCell, { ...col(shown[i], groupBy && i === 0 && 'pl-8'), style: { background: shown[i]?.tint?.(r.original) }, children: i === 0 && nests ? (_jsxs("span", { className: "flex items-center gap-1", children: [opens(r.original) ? (chevron(keyOf(r.original), openLabel())) : (_jsx("span", { className: "-ml-1 size-6 shrink-0" })), flexRender(c.column.columnDef.cell, c.getContext())] })) : (flexRender(c.column.columnDef.cell, c.getContext())) }, c.id)))] }, domain.rowKey(r.original)), openParts.has(keyOf(r.original)) &&
                 partsOf(r.original).map((p) => partRow(p, subgroup?.name)), openParts.has(keyOf(r.original)) && domain.panel ? (_jsx(TableRow, { "data-slot": "row-panel", className: "bg-muted/20 hover:bg-muted/20", children: _jsx(TableCell, { colSpan: shown.length + (selection ? 1 : 0), className: "p-0 whitespace-normal", children: _jsx("div", { className: "sticky left-0 w-[min(56rem,calc(100vw-2rem))] max-w-full px-4 py-3 md:pl-10", children: panelOf(r.original) }) }) }, `panel:${keyOf(r.original)}`)) : null] }, domain.rowKey(r.original)));
     // Rows sharing the sub-group's `under` key fold into one rolled-up line that opens them; a key
     // with one row keeps that row (NVDA opens Shares, then each option).
     const foldRow = (key, members, scope) => {
         const k = `under:${scope}\u0000${key}`;
         const ms = members.map((m) => m.original);
-        return (_jsxs(Fragment, { children: [_jsxs(TableRow, { "data-row": k, children: [selection && _jsx(TableCell, {}), shown.map((f, i) => (_jsx(TableCell, { className: cn(colOf(f), groupBy && i === 0 && 'pl-8'), children: i === 0 ? (_jsxs("span", { className: "flex items-center gap-1", children: [chevron(k, `${key} ${openLabel()}`), _jsx("span", { className: "font-medium", children: key }), _jsx("span", { className: "num text-xs text-muted-foreground", children: ms.length })] })) : (rollCell(f, ms)) }, f.key)))] }), openParts.has(k) && ms.map((p) => partRow(p, subgroup?.name))] }, k));
+        return (_jsxs(Fragment, { children: [_jsxs(TableRow, { "data-row": k, children: [selection && _jsx(TableCell, {}), shown.map((f, i) => (_jsx(TableCell, { ...col(f, groupBy && i === 0 && 'pl-8'), children: i === 0 ? (_jsxs("span", { className: "flex items-center gap-1", children: [chevron(k, `${key} ${openLabel()}`), _jsx("span", { className: "font-medium", children: key }), _jsx("span", { className: "num text-xs text-muted-foreground", children: ms.length })] })) : (rollCell(f, ms)) }, f.key)))] }), openParts.has(k) && ms.map((p) => partRow(p, subgroup?.name))] }, k));
     };
     const rowsOf = (list, scope) => {
         const under = folds ? subgroup?.under : undefined;
@@ -644,32 +671,32 @@ function LumenTableRows({ domain, columns = domain.fields, rows, groupBy = null,
     };
     const box = useRef(null);
     useFloatingHead(box, !inView);
-    return (_jsx("div", { ref: box, className: cn(inView ? IN_VIEW : 'overflow-x-auto overflow-y-hidden [--pin-top:0px]', fit && FIT), children: _jsxs(Table, { children: [_jsx(TableHeader, { children: table.getHeaderGroups().map((hg) => (_jsxs(TableRow, { children: [selection && (_jsx(TableHead, { className: cn('w-8 pr-0', PINNED_HEAD), children: _jsx(Checkbox, { checked: allOn ? true : someOn ? 'indeterminate' : false, onCheckedChange: (on) => toggle(allKeys, on === true), "aria-label": "Select every row" }) })), hg.headers.map((h, i) => (_jsxs(TableHead, { className: cn(colOf(shown[i]), PINNED_HEAD), style: ruleOf(colorOf(domain, shown[i])), onPointerDown: pressStart, onPointerUp: pressEnd, onPointerLeave: pressEnd, onPointerCancel: pressEnd, onContextMenu: (e) => {
-                                    if (press.current)
-                                        e.preventDefault();
-                                }, "aria-sort": h.column.getIsSorted() === 'asc'
-                                    ? 'ascending'
-                                    : h.column.getIsSorted() === 'desc'
-                                        ? 'descending'
-                                        : undefined, children: [i === 0 && groups && (!serverGroups || serverGroups.onToggleAll) && (_jsx(IconButton, { icon: anyClosed ? ChevronsUpDownIcon : ChevronsDownUpIcon, size: "icon-xs", className: "-ml-2 mr-1 align-middle", label: anyClosed ? 'Expand all groups' : 'Collapse all groups', onClick: () => setAll(anyClosed) })), _jsxs(Tooltip, { children: [_jsx(TooltipTrigger, { asChild: true, children: _jsxs(Button, { variant: "ghost", size: "xs", className: cn('font-medium', !(i === 0 && groups) && '-mx-2'), style: { color: colorOf(domain, shown[i]) ?? undefined }, onClick: h.column.getCanSort() ? h.column.getToggleSortingHandler() : undefined, children: [shown[i] ? _jsx(FreshnessMark, { domain: domain, field: shown[i] }) : null, flexRender(h.column.columnDef.header, h.getContext()), _jsx(SortIcon, { dir: h.column.getIsSorted() })] }) }), shown[i] && (domain.groups?.length || freshnessOf(domain, shown[i])) ? (_jsxs(TooltipContent, { children: [domain.groups?.length ? _jsx("div", { children: pathOf(domain, shown[i]) }) : null, freshnessLine(domain, shown[i]) ? (_jsx("div", { children: freshnessLine(domain, shown[i]) })) : null] })) : null] })] }, h.id))), add && (_jsx(TableHead, { className: cn('w-8 pl-1', PINNED_HEAD), children: _jsx(AddColumnMenu, { add: add, fieldOpen: fieldOpen, onFieldOpen: setFieldOpen }) }))] }, hg.id))) }), _jsxs(TableBody, { children: [!rows.length && !serverGroups?.list?.length && (_jsx(TableRow, { children: _jsx(TableCell, { colSpan: span, className: "py-6 text-center text-muted-foreground", children: "No rows match." }) })), groups && groupBy
-                            ? groups.map(([key, members], gi) => {
-                                const open = isOpen(key, gi);
-                                return (_jsxs(Fragment, { children: [_jsxs(TableRow, { className: ROLLUP, "data-group": key, children: [selection && (_jsx(TableCell, { className: cn('w-8 pr-0', PINNED_GROUP), children: _jsx(Checkbox, { checked: members.every((m) => selection.keys.has(keyOf(m.original)))
-                                                            ? true
-                                                            : members.some((m) => selection.keys.has(keyOf(m.original)))
-                                                                ? 'indeterminate'
-                                                                : false, onCheckedChange: (on) => toggle(members.map((m) => keyOf(m.original)), on === true), "aria-label": `Select every row of ${key}` }) })), shown.slice(lead - 1).map((f, i) => i === 0 ? (_jsxs(TableCell, { colSpan: leadSpan, className: PINNED_GROUP, children: [_jsxs(Button, { variant: "ghost", size: "xs", className: "-mx-2 hover:bg-transparent aria-expanded:bg-transparent", "aria-expanded": open, "aria-label": `${open ? 'Collapse' : 'Expand'} ${key}`, onClick: () => serverGroups
-                                                                ? serverGroups.onToggle(key)
-                                                                : setFlipped((c) => {
-                                                                    const n = new Set(c);
-                                                                    n.has(key) ? n.delete(key) : n.add(key);
-                                                                    return n;
-                                                                }), children: [_jsx(ChevronRightIcon, { className: cn('transition-transform', open && 'rotate-90') }), _jsx(groupBy.icon, {}), key, _jsx("span", { className: "num font-normal text-muted-foreground", children: serverGroups
-                                                                        ? (served.get(key)?.n?.toLocaleString() ?? '')
-                                                                        : members.length })] }), groupActions?.(key, members.map((m) => m.original))] }, f.key)) : (_jsx(TableCell, { className: cn(colOf(f), PINNED_GROUP), children: !serverGroups &&
-                                                        rollCell(f, members.map((m) => m.original)) }, f.key)))] }), open && (serverGroups ? servedRows(members, key) : drawn(members, key))] }, key));
-                            })
-                            : drawn(sorted, ''), serverGroups?.more && !serverGroups.pages && (_jsx(TableRow, { "data-more": true, children: _jsx(TableCell, { colSpan: span, className: "py-1", children: _jsxs(Button, { variant: "ghost", size: "xs", onClick: serverGroups.more, children: [_jsx(ChevronsDownIcon, {}), "More groups"] }) }) })), hasTotal && rows.length > 0 && (_jsxs(TableRow, { className: cn(ROLLUP, 'border-t-2'), "data-total": true, children: [selection && _jsx(TableCell, {}), rollCells(rows).map((cell, i) => i === 0 && !(shown[0] && rollsUp(shown[0])) ? (_jsx(TableCell, { children: "Total" }, "total")) : (cell))] }))] })] }) }));
+    return (_jsx("div", { ref: box, className: cn(inView ? IN_VIEW : 'overflow-x-auto overflow-y-hidden [--pin-top:0px]', fit && FIT), children: _jsx(UnitColumns.Provider, { value: markUnits, children: _jsxs(Table, { children: [_jsx(TableHeader, { children: table.getHeaderGroups().map((hg) => (_jsxs(TableRow, { children: [selection && (_jsx(TableHead, { className: cn('w-8 pr-0', PINNED_HEAD), children: _jsx(Checkbox, { checked: allOn ? true : someOn ? 'indeterminate' : false, onCheckedChange: (on) => toggle(allKeys, on === true), "aria-label": "Select every row" }) })), hg.headers.map((h, i) => (_jsxs(TableHead, { ...col(shown[i], PINNED_HEAD), style: ruleOf(colorOf(domain, shown[i])), onPointerDown: pressStart, onPointerUp: pressEnd, onPointerLeave: pressEnd, onPointerCancel: pressEnd, onContextMenu: (e) => {
+                                        if (press.current)
+                                            e.preventDefault();
+                                    }, "aria-sort": h.column.getIsSorted() === 'asc'
+                                        ? 'ascending'
+                                        : h.column.getIsSorted() === 'desc'
+                                            ? 'descending'
+                                            : undefined, children: [i === 0 && groups && (!serverGroups || serverGroups.onToggleAll) && (_jsx(IconButton, { icon: anyClosed ? ChevronsUpDownIcon : ChevronsDownUpIcon, size: "icon-xs", className: "-ml-2 mr-1 align-middle", label: anyClosed ? 'Expand all groups' : 'Collapse all groups', onClick: () => setAll(anyClosed) })), _jsxs(Tooltip, { children: [_jsx(TooltipTrigger, { asChild: true, children: _jsxs(Button, { variant: "ghost", size: "xs", className: cn('font-medium', !(i === 0 && groups) && '-mx-2'), style: { color: colorOf(domain, shown[i]) ?? undefined }, onClick: h.column.getCanSort() ? h.column.getToggleSortingHandler() : undefined, children: [shown[i] ? _jsx(FreshnessMark, { domain: domain, field: shown[i] }) : null, flexRender(h.column.columnDef.header, h.getContext()), _jsx(SortIcon, { dir: h.column.getIsSorted() })] }) }), shown[i] && (domain.groups?.length || freshnessOf(domain, shown[i])) ? (_jsxs(TooltipContent, { children: [domain.groups?.length ? _jsx("div", { children: pathOf(domain, shown[i]) }) : null, freshnessLine(domain, shown[i]) ? (_jsx("div", { children: freshnessLine(domain, shown[i]) })) : null] })) : null] })] }, h.id))), add && (_jsx(TableHead, { className: cn('w-8 pl-1', PINNED_HEAD), children: _jsx(AddColumnMenu, { add: add, fieldOpen: fieldOpen, onFieldOpen: setFieldOpen }) }))] }, hg.id))) }), _jsxs(TableBody, { children: [!rows.length && !serverGroups?.list?.length && (_jsx(TableRow, { children: _jsx(TableCell, { colSpan: span, className: "py-6 text-center text-muted-foreground", children: "No rows match." }) })), groups && groupBy
+                                ? groups.map(([key, members], gi) => {
+                                    const open = isOpen(key, gi);
+                                    return (_jsxs(Fragment, { children: [_jsxs(TableRow, { className: ROLLUP, "data-group": key, children: [selection && (_jsx(TableCell, { className: cn('w-8 pr-0', PINNED_GROUP), children: _jsx(Checkbox, { checked: members.every((m) => selection.keys.has(keyOf(m.original)))
+                                                                ? true
+                                                                : members.some((m) => selection.keys.has(keyOf(m.original)))
+                                                                    ? 'indeterminate'
+                                                                    : false, onCheckedChange: (on) => toggle(members.map((m) => keyOf(m.original)), on === true), "aria-label": `Select every row of ${key}` }) })), shown.slice(lead - 1).map((f, i) => i === 0 ? (_jsxs(TableCell, { colSpan: leadSpan, className: PINNED_GROUP, children: [_jsxs(Button, { variant: "ghost", size: "xs", className: "-mx-2 hover:bg-transparent aria-expanded:bg-transparent", "aria-expanded": open, "aria-label": `${open ? 'Collapse' : 'Expand'} ${key}`, onClick: () => serverGroups
+                                                                    ? serverGroups.onToggle(key)
+                                                                    : setFlipped((c) => {
+                                                                        const n = new Set(c);
+                                                                        n.has(key) ? n.delete(key) : n.add(key);
+                                                                        return n;
+                                                                    }), children: [_jsx(ChevronRightIcon, { className: cn('transition-transform', open && 'rotate-90') }), _jsx(groupBy.icon, {}), key, _jsx("span", { className: "num font-normal text-muted-foreground", children: serverGroups
+                                                                            ? (served.get(key)?.n?.toLocaleString() ?? '')
+                                                                            : members.length })] }), groupActions?.(key, members.map((m) => m.original))] }, f.key)) : (_jsx(TableCell, { ...col(f, PINNED_GROUP), children: !serverGroups &&
+                                                            rollCell(f, members.map((m) => m.original)) }, f.key)))] }), open && (serverGroups ? servedRows(members, key) : drawn(members, key))] }, key));
+                                })
+                                : drawn(sorted, ''), serverGroups?.more && !serverGroups.pages && (_jsx(TableRow, { "data-more": true, children: _jsx(TableCell, { colSpan: span, className: "py-1", children: _jsxs(Button, { variant: "ghost", size: "xs", onClick: serverGroups.more, children: [_jsx(ChevronsDownIcon, {}), "More groups"] }) }) })), hasTotal && rows.length > 0 && (_jsxs(TableRow, { className: cn(ROLLUP, 'border-t-2'), "data-total": true, children: [selection && _jsx(TableCell, {}), rollCells(rows).map((cell, i) => i === 0 && !(shown[0] && rollsUp(shown[0])) ? (_jsx(TableCell, { children: "Total" }, "total")) : (cell))] }))] })] }) }) }));
 }
 /** One value rolled up into a rows × columns grid, with totals where the roll-up adds. */
 function PivotTable({ domain, rows, pivot, }) {

package/dist/pace.d.ts

@@ -0,0 +1,53 @@
+/** The windows a pace is read over. */
+export declare const PACE_WINDOWS: readonly [{
+    readonly id: '6h';
+    readonly hours: 6;
+}, {
+    readonly id: '12h';
+    readonly hours: 12;
+}, {
+    readonly id: '24h';
+    readonly hours: 24;
+}, {
+    readonly id: '7d';
+    readonly hours: 168;
+}];
+export type PaceWindow = (typeof PACE_WINDOWS)[number]['id'];
+export declare const paceHours: (w: PaceWindow) => 6 | 12 | 24 | 168;
+export interface BurnRate {
+    /** Units per hour; a stored amount's growth per hour (can be negative). */
+    rate: number;
+    /** The plain average, before a lone spike was capped. */
+    raw: number;
+    /** Lone hot samples that were capped. */
+    spikes: number;
+}
+/**
+ * The rate over `samples` (oldest first, complete periods only), each `per` hours long. `gauge`:
+ * the samples are sizes, so the rate is their growth from first to last. `damp: false` keeps spikes.
+ */
+export declare function burnRate(samples: readonly number[], { per, gauge, damp }?: {
+    per?: number;
+    gauge?: boolean;
+    damp?: boolean;
+}): BurnRate;
+export interface Pace extends BurnRate {
+    /** Hours until the cap at this rate: 0 when already there, Infinity when not growing. */
+    eta: number;
+    /** Where the meter lands at reset, as a share of the cap (1.2 = 120%). */
+    atReset: number;
+    /** Reaches the cap before it resets. */
+    hits: boolean;
+    /** Hours until the cap resets (or the horizon for a stored amount). */
+    resetIn: number;
+    /** The rate that lands exactly on the cap at reset (0 once there). */
+    safe: number;
+}
+/** When `used` reaches `cap` at `rate`, and where it stands when the cap resets in `resetIn` hours. */
+export declare function timeToCap(rate: BurnRate, used: number, cap: number, resetIn: number): Pace;
+/** `40m`, `2h 05m`, `29h`, `3 days`; `short` gives `2h`, `29h`, `3d` (a phone cell). */
+export declare function durationText(hours: number, short?: boolean): string;
+/** The app's window before anyone picks one (`12h` unless set). */
+export declare function setDefaultPaceWindow(w: PaceWindow): void;
+/** The pace window in use and its setter; every `PaceWindowPicker` and reader shares it. */
+export declare function usePaceWindow(): [PaceWindow, (w: PaceWindow) => void];

package/dist/pace.js

@@ -0,0 +1,120 @@
+// Pace: how fast a meter is being used over a recent window, carried forward to when it reaches its
+// cap. The same for every product: the app passes the window's samples (hourly or daily amounts, or
+// sizes for a stored amount), what is used so far, the cap and the hours until the cap resets.
+// A lone hot sample (above 3× the window's median, with neither neighbour above it) counts as 3×
+// the median, so one burst can't fake a crisis; a run of hot samples is a real change and counts.
+// `TimeToCap` draws the answer; its colour is where the meter lands at reset, on the meter levels.
+import { useCallback, useSyncExternalStore } from 'react';
+/** The windows a pace is read over. */
+export const PACE_WINDOWS = [
+    { id: '6h', hours: 6 },
+    { id: '12h', hours: 12 },
+    { id: '24h', hours: 24 },
+    { id: '7d', hours: 168 },
+];
+export const paceHours = (w) => PACE_WINDOWS.find((x) => x.id === w)?.hours ?? 12;
+const median = (xs) => {
+    const s = [...xs].sort((a, b) => a - b);
+    return s[Math.floor(s.length / 2)] ?? 0;
+};
+/**
+ * The rate over `samples` (oldest first, complete periods only), each `per` hours long. `gauge`:
+ * the samples are sizes, so the rate is their growth from first to last. `damp: false` keeps spikes.
+ */
+export function burnRate(samples, { per = 1, gauge = false, damp = true } = {}) {
+    const n = samples.length;
+    if (!n)
+        return { rate: 0, raw: 0, spikes: 0 };
+    if (gauge) {
+        const r = n > 1 ? ((samples[n - 1] ?? 0) - (samples[0] ?? 0)) / ((n - 1) * per) : 0;
+        return { rate: r, raw: r, spikes: 0 };
+    }
+    const total = samples.reduce((s, v) => s + v, 0);
+    const cap = median(samples) * 3;
+    const hot = (i) => cap > 0 && i >= 0 && i < n && (samples[i] ?? 0) > cap;
+    let kept = 0;
+    let spikes = 0;
+    for (let i = 0; i < n; i++) {
+        if (damp && hot(i) && !hot(i - 1) && !hot(i + 1)) {
+            kept += cap;
+            spikes++;
+        }
+        else
+            kept += samples[i] ?? 0;
+    }
+    const hours = n * per;
+    return { rate: kept / hours, raw: total / hours, spikes };
+}
+/** When `used` reaches `cap` at `rate`, and where it stands when the cap resets in `resetIn` hours. */
+export function timeToCap(rate, used, cap, resetIn) {
+    const left = cap - used;
+    const eta = left <= 0 ? 0 : rate.rate > 0 ? left / rate.rate : Number.POSITIVE_INFINITY;
+    return {
+        ...rate,
+        eta,
+        atReset: cap > 0 ? (used + Math.max(rate.rate, 0) * resetIn) / cap : 0,
+        hits: eta <= resetIn,
+        resetIn,
+        safe: left > 0 && resetIn > 0 ? left / resetIn : 0,
+    };
+}
+/** `40m`, `2h 05m`, `29h`, `3 days`; `short` gives `2h`, `29h`, `3d` (a phone cell). */
+export function durationText(hours, short = false) {
+    if (!Number.isFinite(hours))
+        return '—';
+    if (hours < 1)
+        return `${Math.max(1, Math.round(hours * 60))}m`;
+    if (short)
+        return hours < 48 ? `${Math.round(hours)}h` : `${Math.round(hours / 24)}d`;
+    if (hours < 10) {
+        const h = Math.floor(hours);
+        const m = Math.round((hours - h) * 60);
+        return m === 60 ? `${h + 1}h 00m` : `${h}h ${String(m).padStart(2, '0')}m`;
+    }
+    return hours < 48 ? `${Math.round(hours)}h` : `${Math.round(hours / 24)} days`;
+}
+// The window someone picked, kept in their browser (one choice per app host, every page shares it).
+const KEY = 'lumen:pace-window';
+const listeners = new Set();
+let picked = null;
+let fallback = '12h';
+const isWindow = (v) => PACE_WINDOWS.some((x) => x.id === v);
+function read() {
+    if (picked)
+        return picked;
+    try {
+        const v = localStorage.getItem(KEY);
+        if (isWindow(v))
+            picked = v;
+    }
+    catch {
+        // Storage refused: the app's default holds.
+    }
+    return picked ?? fallback;
+}
+function write(w) {
+    picked = w;
+    try {
+        localStorage.setItem(KEY, w);
+    }
+    catch {
+        // Storage refused: the pick holds until reload.
+    }
+    for (const l of listeners)
+        l();
+}
+const subscribe = (l) => {
+    listeners.add(l);
+    return () => listeners.delete(l);
+};
+/** The app's window before anyone picks one (`12h` unless set). */
+export function setDefaultPaceWindow(w) {
+    fallback = w;
+    for (const l of listeners)
+        l();
+}
+/** The pace window in use and its setter; every `PaceWindowPicker` and reader shares it. */
+export function usePaceWindow() {
+    const w = useSyncExternalStore(subscribe, read, () => fallback);
+    return [w, useCallback((x) => write(x), [])];
+}

package/dist/theme.css

@@ -95,6 +95,10 @@
   --row-h: 28px;
   --cell-x: 8px;
   --cell-y: 4px;
+  /* A UnitValue's unit slot (`GB`, `%`, `/day`), hung in the gutter of a units column. */
+  --unit-slot: 2rem;
+  /* A table's first (name) column stops growing here; longer names end in an ellipsis. */
+  --lead-col-max: 18rem;
 
   --background: #f4f6fa;
   --foreground: #121826;
@@ -388,6 +392,20 @@
   }
 }
 
+/* A table column a UnitValue drew in (`data-units`, set by LumenView): every cell, header and
+   Total included, right-aligns on the numbers' edge; each UnitValue's unit slot hangs in the
+   widened gutter (out of flow, so no wrapper an app puts round it can shift it). One column, one edge, whatever an app's render draws beside it. */
+[data-units] {
+  padding-right: calc(var(--cell-x) + var(--unit-slot));
+}
+[data-units] [data-slot="unit-value"] {
+  position: relative;
+}
+[data-units] [data-slot="unit-value-unit"] {
+  position: absolute;
+  left: 100%;
+}
+
 @layer utilities {
   .bg-gap-hatch {
     background: repeating-linear-gradient(135deg, var(--gap) 0 3px, var(--gap-soft) 3px 6px);

package/dist/time-to-cap.d.ts

@@ -0,0 +1,25 @@
+import type { MeterLevels } from '@columenlabs/lumen-ui-types/views';
+import type { ReactNode } from 'react';
+import { meterLevel } from './meter-level.js';
+import { type Pace } from './pace.js';
+/** Picks the pace window (6h, 12h, 24h, 7d) for every page at once; a header action. */
+export declare function PaceWindowPicker({ className }: {
+    className?: string;
+}): import("react").JSX.Element;
+/** What a pace reads as: the words and the level they're coloured by. */
+export declare function paceText(p: Pace, short?: boolean): {
+    text: string;
+    level: ReturnType<typeof meterLevel>;
+};
+/**
+ * One meter's time to its cap at the pace window's rate. `label` names the meter when it isn't the
+ * one the row already shows; `short` is the phone cell (`2h`, `3d`, `—`).
+ */
+export declare function TimeToCap({ pace, label, short, levels, className, }: {
+    pace: Pace | null;
+    label?: ReactNode;
+    short?: boolean;
+    /** This cell's own levels; left out, the app's `meterLevels`. */
+    levels?: Partial<MeterLevels>;
+    className?: string;
+}): import("react").JSX.Element;

package/dist/time-to-cap.js

@@ -0,0 +1,45 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ZapIcon } from 'lucide-react';
+import { useIsMobile } from './hooks/use-mobile.js';
+import { cn } from './lib/utils.js';
+import { LumenSelector } from './lumen-selector.js';
+import { METER_LEVEL_COLOR, meterLevel } from './meter-level.js';
+import { PACE_WINDOWS, durationText, usePaceWindow } from './pace.js';
+import { ToggleGroup, ToggleGroupItem } from './ui/toggle-group.js';
+/** Picks the pace window (6h, 12h, 24h, 7d) for every page at once; a header action. */
+export function PaceWindowPicker({ className }) {
+    const [w, setW] = usePaceWindow();
+    const mobile = useIsMobile();
+    if (mobile)
+        return (_jsx(LumenSelector, { trigger: "chip", icon: ZapIcon, label: "Pace window", size: "sm", align: "end", value: w, onChange: (v) => setW(v), options: PACE_WINDOWS.map((x) => ({ value: x.id, label: x.id, detail: `last ${x.id}` })), className: className }));
+    return (_jsxs(ToggleGroup, { type: "single", variant: "outline", size: "sm", spacing: 0, value: w, onValueChange: (v) => v && setW(v), "aria-label": "Pace window", title: "Pace: the rate over the last\u2026", className: className, children: [_jsxs("span", { className: "flex h-8 items-center gap-1 rounded-l-md border border-r-0 px-2 text-muted-foreground text-xs", children: [_jsx(ZapIcon, { className: "size-3.5" }), "Pace"] }), PACE_WINDOWS.map((x) => (_jsx(ToggleGroupItem, { value: x.id, className: "num px-2.5 text-xs", children: x.id }, x.id)))] }));
+}
+/** What a pace reads as: the words and the level they're coloured by. */
+export function paceText(p, short = false) {
+    if (p.eta === 0)
+        return { text: short ? 'cap' : 'At cap', level: 'alert' };
+    const level = meterLevel(p.atReset);
+    if (p.hits)
+        return { text: short ? durationText(p.eta, true) : `in ${durationText(p.eta)}`, level };
+    return { text: short ? '—' : 'Resets first', level: short ? 'ok' : level };
+}
+/**
+ * One meter's time to its cap at the pace window's rate. `label` names the meter when it isn't the
+ * one the row already shows; `short` is the phone cell (`2h`, `3d`, `—`).
+ */
+export function TimeToCap({ pace, label, short, levels, className, }) {
+    if (!pace)
+        return _jsx("span", { className: "text-muted-foreground", children: "\u2014" });
+    const t = paceText(pace, short);
+    const level = levels && pace.eta > 0 ? meterLevel(pace.atReset, levels) : t.level;
+    const c = METER_LEVEL_COLOR[level];
+    const quiet = level === 'ok' && !pace.hits;
+    return (_jsxs("span", { className: cn('inline-flex h-5 min-w-0 items-center gap-1.5 whitespace-nowrap rounded-sm text-xs', quiet ? 'text-muted-foreground' : 'px-1.5', className), style: quiet
+            ? undefined
+            : level === 'ok'
+                ? { background: 'var(--muted)' }
+                : {
+                    background: `color-mix(in oklab, ${c} 18%, transparent)`,
+                    color: `color-mix(in oklab, ${c} 80%, var(--foreground))`,
+                }, children: [label && _jsx("span", { className: "truncate max-md:max-w-16", children: label }), _jsx("span", { className: "num", children: t.text })] }));
+}

package/dist/unit-value.d.ts

@@ -1,5 +1,7 @@
 import type { MeterLevels } from '@columenlabs/lumen-ui-types/views';
-import type { ReactNode } from 'react';
+import { type ReactNode } from 'react';
+/** Set by a table: marks the column (its cell's `data-col`) a UnitValue draws in. */
+export declare const UnitColumns: import("react").Context<((col: string) => void) | null>;
 export declare function UnitValue({ value, unit, tone: toneProp, share, levels, title, className, }: {
     /** The number, already formatted (`231.4`). */
     value: ReactNode;

package/dist/unit-value.js

@@ -1,7 +1,18 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createContext, useContext, useLayoutEffect, useRef } from 'react';
 import { cn } from './lib/utils.js';
 import { meterValueTone } from './meter-level.js';
+/** Set by a table: marks the column (its cell's `data-col`) a UnitValue draws in. */
+export const UnitColumns = createContext(null);
 export function UnitValue({ value, unit, tone: toneProp, share, levels, title, className, }) {
     const tone = toneProp ?? (share === undefined ? undefined : meterValueTone(share, levels));
-    return (_jsxs("span", { title: title, className: cn('inline-flex w-full items-center justify-end gap-1 whitespace-nowrap', className), children: [_jsx("span", { className: cn('num text-right', tone === 'warning' && 'text-warning', tone === 'loss' && 'text-loss'), children: value }), _jsx("span", { className: "w-10 shrink-0 text-left text-muted-foreground text-xs", children: unit }), _jsx("span", { "aria-hidden": "true", className: cn('size-1.5 shrink-0 rounded-full', tone === 'warning' ? 'bg-warning' : tone === 'loss' ? 'bg-loss' : 'bg-transparent') })] }));
+    const mark = useContext(UnitColumns);
+    const ref = useRef(null);
+    // Before paint, so the column never draws on two edges, even for a frame.
+    useLayoutEffect(() => {
+        const col = ref.current?.closest('[data-col]')?.getAttribute('data-col');
+        if (mark && col)
+            mark(col);
+    }, [mark]);
+    return (_jsxs("span", { ref: ref, "data-slot": "unit-value", title: title, className: cn('inline-flex w-full items-center justify-end whitespace-nowrap', className), children: [_jsxs("span", { className: cn('num relative text-right', tone === 'warning' && 'text-warning', tone === 'loss' && 'text-loss'), children: [tone && (_jsx("span", { "aria-hidden": "true", className: cn('-translate-y-1/2 absolute top-1/2 right-full mr-1 size-1.5 rounded-full', tone === 'warning' ? 'bg-warning' : 'bg-loss') })), value] }), _jsx("span", { "data-slot": "unit-value-unit", className: "w-(--unit-slot) shrink-0 pl-1 text-left text-muted-foreground text-xs", children: unit })] }));
 }

package/dist/view-model.d.ts

@@ -129,6 +129,12 @@ export interface ViewField<T> {
     }> | undefined;
     /** The cell's background, a theme colour mix (a P/L heat grid). */
     tint?: (row: T) => string | undefined;
+    /**
+     * The column's widest cell, a CSS length (`14rem`): past it the cell ends in an ellipsis on one
+     * line, the full text in its hover. The first column defaults to `--lead-col-max` (18rem);
+     * `false` lets it grow.
+     */
+    maxWidth?: string | false;
     /** Left out on phones, where the table has no room for it (a returns table's longer windows). */
     hideOnPhone?: boolean;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@columenlabs/lumen-ui",
-  "version": "0.1.54",
+  "version": "0.1.56",
   "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.54",
+    "@columenlabs/lumen-ui-types": "0.1.56",
     "@dnd-kit/core": "6.3.1",
     "@dnd-kit/sortable": "10.0.0",
     "@dnd-kit/utilities": "3.2.2",