@columenlabs/lumen-ui 0.1.56 → 0.1.58

package/README.md

@@ -81,7 +81,8 @@ Every export, its props and an example are on the [docs](https://lumen.columenla
 - 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.
+- 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). Where most hours are empty (median 0) a lone nonzero hour counts as 0, and a window with too little use (`timeToCap(..., { minTotal })`, default 0.1% of the cap) is `thin`: no time to the cap. Don't hand-roll ETAs or a window toggle.
+- A change between periods (this week against last) is `trendChange(now, prev, { minBase })` drawn by `TrendValue`: `▲ 12%` over a big enough earlier period, the plain difference `▲ +3` when it is at or under `minBase`, `▲ >10×` past ten times. A % over a near-empty baseline misleads; never show one.
 - 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

@@ -26,6 +26,7 @@ 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 { type TrendChange, TrendValue, trendChange } from './trend-value.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

@@ -33,6 +33,7 @@ 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 { TrendValue, trendChange } from './trend-value.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-selector.js

@@ -24,6 +24,8 @@ import { Sheet, SheetContent, SheetDescription, SheetTitle } from './ui/sheet.js
 import { Tooltip, TooltipContent, TooltipTrigger } from './ui/tooltip.js';
 const SHOWN = 6;
 const SEARCH_PAST = 8;
+/** Room below a trigger (px) under which its list opens above, when there is more room there. */
+const ROOM_BELOW = 320;
 const CHIPS = 4;
 const CREATE = '\u0000create';
 /** The options as groups, in order. */
@@ -163,9 +165,19 @@ export function LumenSelector(props) {
     // focus back out of a list portalled to the body, so its search box could never be typed in.
     const markRef = useRef(null);
     const [host, setHost] = useState(null);
+    // The list opens below its trigger, or above when the room below is short and there is more
+    // above (a row near the screen's foot); either way it fits the screen, its footer in view.
+    const triggerRef = useRef(null);
+    const [side, setSide] = useState('bottom');
     useLayoutEffect(() => {
-        if (open)
-            setHost(markRef.current?.closest('[role="dialog"]') ?? null);
+        if (!open)
+            return;
+        setHost(markRef.current?.closest('[role="dialog"]') ?? null);
+        const r = (chipsRef.current ?? triggerRef.current)?.getBoundingClientRect();
+        if (!r)
+            return;
+        const below = window.innerHeight - r.bottom;
+        setSide(below < ROOM_BELOW && r.top > below ? 'top' : 'bottom');
     }, [open]);
     const setOpen = (o) => {
         setOwnOpen(o);
@@ -225,11 +237,11 @@ export function LumenSelector(props) {
     const selected = multiple ? null : (byValue.get(values[0] ?? '') ?? null);
     const Lead = selected?.icon ?? LeadIcon;
     const fieldInside = (_jsxs(_Fragment, { children: [Lead && _jsx(Lead, { className: "text-muted-foreground" }), _jsx("span", { className: cn('min-w-0 flex-1 truncate text-left', !selected && !values.length && 'text-muted-foreground'), children: selected ? (selected.content ?? selected.label) : values[0] ? values[0] : placeholder }), _jsx(ChevronDownIcon, { className: "pointer-events-none size-4 text-muted-foreground" })] }));
-    const list = (_jsxs(_Fragment, { children: [header, _jsx(Base.List, { className: cn('overscroll-contain p-1 data-empty:p-0', phone
-                    ? 'min-h-0 flex-1 overflow-y-auto pb-4'
-                    : 'max-h-[min(22rem,calc(var(--available-height)-3rem))] scroll-pt-8 overflow-y-auto'), children: _jsx(Rows, { shown: rows, picked: picked, multiple: multiple, full: full, expand: expand }) }), _jsx(Base.Empty, { className: "hidden px-2 py-3 text-center text-sm text-muted-foreground group-data-empty/selector:block", children: empty })] }));
+    // On a desktop the popup is a column as tall as the screen allows: the search, header and
+    // footer keep their height and the list between them scrolls.
+    const list = (_jsxs(_Fragment, { children: [header && _jsx("div", { className: "shrink-0", children: header }), _jsx(Base.List, { className: cn('min-h-0 overscroll-contain p-1 data-empty:p-0', phone ? 'flex-1 overflow-y-auto pb-4' : 'max-h-88 flex-1 scroll-pt-8 overflow-y-auto'), children: _jsx(Rows, { shown: rows, picked: picked, multiple: multiple, full: full, expand: expand }) }), _jsx(Base.Empty, { className: "hidden px-2 py-3 text-center text-sm text-muted-foreground group-data-empty/selector:block", children: empty })] }));
     const clearAll = multiple && values.length > 0 && (_jsx("button", { type: "button", className: "text-xs text-muted-foreground hover:text-foreground", onClick: () => props.onChange([]), children: "Clear all" }));
-    const searchBox = (_jsxs("div", { className: cn('flex items-center gap-2 border-b px-2', phone ? 'mx-4 h-11 rounded-md border' : 'h-9', !searchable && 'sr-only'), children: [_jsx(SearchIcon, { className: "size-4 shrink-0 text-muted-foreground" }), _jsx(Base.Input, { readOnly: !searchable, placeholder: create ? 'Search or type a new one' : `Search ${count}`, "aria-label": label ? `Search ${label}` : 'Search', className: "h-full min-w-0 flex-1 bg-transparent text-sm outline-none placeholder:text-muted-foreground max-md:text-[15px]" })] }));
+    const searchBox = (_jsxs("div", { className: cn('flex shrink-0 items-center gap-2 border-b px-2', phone ? 'mx-4 h-11 rounded-md border' : 'h-9', !searchable && 'sr-only'), children: [_jsx(SearchIcon, { className: "size-4 shrink-0 text-muted-foreground" }), _jsx(Base.Input, { readOnly: !searchable, placeholder: create ? 'Search or type a new one' : `Search ${count}`, "aria-label": label ? `Search ${label}` : 'Search', className: "h-full min-w-0 flex-1 bg-transparent text-sm outline-none placeholder:text-muted-foreground max-md:text-[15px]" })] }));
     const rootProps = {
         items: rows.map((g) => ({ value: g.label, items: g.rows.map((o) => o.value) })),
         filteredItems: rows.map((g) => ({ value: g.label, items: g.rows.map((o) => o.value) })),
@@ -256,8 +268,8 @@ export function LumenSelector(props) {
                         // No ring on the first button: the person taps what they want.
                         onOpenAutoFocus: (e) => e.preventDefault(), className: "group/selector flex max-h-[85dvh] flex-col gap-2 rounded-t-xl pt-2", children: [_jsx("span", { "aria-hidden": true, className: "mx-auto h-1 w-9 rounded-full bg-border" }), _jsxs("div", { className: "flex items-center justify-between px-4", children: [_jsx(SheetTitle, { id: sheetTitle, children: label ?? placeholder }), multiple && (_jsx(Button, { size: "sm", onClick: () => setOpen(false), children: "Done" }))] }), _jsx(SheetDescription, { className: "sr-only", children: multiple ? 'Pick any, then Done' : 'Pick one' }), _jsxs(Base.Root, { ...rootProps, inline: true, open: true, onOpenChange: () => undefined, multiple: multiple, value: multiple ? [...values] : (values[0] ?? null), onValueChange: (v) => pick(v), children: [multiple && values.length > 0 && (_jsx("div", { className: "flex flex-wrap gap-1.5 px-4", children: values.map((v) => (_jsx("span", { className: "rounded-sm bg-muted px-2 py-1 text-[13px]", children: labelOf(v) }, v))) })), searchable && searchBox, list] }), multiple && (_jsxs("div", { className: "flex items-center justify-between border-t px-4 pt-3 pb-5", children: [_jsxs("span", { className: "text-xs text-muted-foreground", children: [values.length, " picked"] }), clearAll] }))] }) })] }));
     }
-    const popup = (_jsx(Base.Portal, { container: host ?? undefined, children: _jsx(Base.Positioner, { side: "bottom", sideOffset: 4, align: align, anchor: inChips ? chipsRef : undefined, className: "pointer-events-auto isolate z-[60]", children: _jsxs(Base.Popup, { "data-slot": "lumen-selector", className: "group/selector max-w-(--available-width) min-w-[max(var(--anchor-width),14rem)] origin-(--transform-origin) overflow-hidden rounded-lg bg-popover text-popover-foreground shadow-md ring-1 ring-foreground/10 duration-100 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95", children: [!inChips && searchBox, list, multiple && (_jsxs("div", { className: "flex items-center gap-3 border-t px-2 py-1.5", children: [_jsxs("span", { className: "text-xs text-muted-foreground", children: [values.length, " picked", max !== undefined ? ` of ${max}` : ''] }), clearAll, _jsx(Button, { size: "xs", className: "ml-auto", onClick: () => setOpen(false), children: "Done" })] }))] }) }) }));
-    return (_jsxs(Base.Root, { ...rootProps, multiple: multiple, value: multiple ? [...values] : (values[0] ?? null), onValueChange: (v) => pick(v), children: [inChips ? (_jsxs(Base.Chips, { ref: chipsRef, className: cn('flex min-h-8 flex-wrap items-center gap-1 rounded-lg border border-input bg-transparent px-1 py-1 text-sm transition-colors focus-within:border-ring focus-within:ring-3 focus-within:ring-ring/50 dark:bg-input/30', className), children: [chips, _jsx(Base.Input, { id: id, "aria-label": label, disabled: disabled, readOnly: !searchable, placeholder: values.length ? '' : placeholder, className: "min-w-16 flex-1 bg-transparent px-1 outline-none placeholder:text-muted-foreground" })] })) : trigger === 'icon' ? (_jsxs(Tooltip, { children: [_jsx(TooltipTrigger, { asChild: true, children: _jsx(Base.Trigger, { render: _jsx(Button, { variant: "ghost", size: "icon-sm", "aria-label": label, className: className }), children: LeadIcon && _jsx(LeadIcon, {}) }) }), _jsx(TooltipContent, { children: label })] })) : (_jsx(Base.Trigger, { id: id, "data-size": size, "aria-label": label, className: cn(FIELD, trigger === 'chip' && 'rounded-full', className), children: fieldInside })), _jsx("span", { ref: markRef, hidden: true }), popup] }));
+    const popup = (_jsx(Base.Portal, { container: host ?? undefined, children: _jsx(Base.Positioner, { side: side, sideOffset: 4, align: align, anchor: inChips ? chipsRef : undefined, className: "pointer-events-auto isolate z-[60]", children: _jsxs(Base.Popup, { "data-slot": "lumen-selector", className: "group/selector flex max-h-(--available-height) max-w-(--available-width) flex-col min-w-[max(var(--anchor-width),14rem)] origin-(--transform-origin) overflow-hidden rounded-lg bg-popover text-popover-foreground shadow-md ring-1 ring-foreground/10 duration-100 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95", children: [!inChips && searchBox, list, multiple && (_jsxs("div", { className: "flex shrink-0 items-center gap-3 border-t px-2 py-1.5", children: [_jsxs("span", { className: "text-xs text-muted-foreground", children: [values.length, " picked", max !== undefined ? ` of ${max}` : ''] }), clearAll, _jsx(Button, { size: "xs", className: "ml-auto", onClick: () => setOpen(false), children: "Done" })] }))] }) }) }));
+    return (_jsxs(Base.Root, { ...rootProps, multiple: multiple, value: multiple ? [...values] : (values[0] ?? null), onValueChange: (v) => pick(v), children: [inChips ? (_jsxs(Base.Chips, { ref: chipsRef, className: cn('flex min-h-8 flex-wrap items-center gap-1 rounded-lg border border-input bg-transparent px-1 py-1 text-sm transition-colors focus-within:border-ring focus-within:ring-3 focus-within:ring-ring/50 dark:bg-input/30', className), children: [chips, _jsx(Base.Input, { id: id, "aria-label": label, disabled: disabled, readOnly: !searchable, placeholder: values.length ? '' : placeholder, className: "min-w-16 flex-1 bg-transparent px-1 outline-none placeholder:text-muted-foreground" })] })) : trigger === 'icon' ? (_jsxs(Tooltip, { children: [_jsx(TooltipTrigger, { asChild: true, children: _jsx(Base.Trigger, { ref: triggerRef, render: _jsx(Button, { variant: "ghost", size: "icon-sm", "aria-label": label, className: className }), children: LeadIcon && _jsx(LeadIcon, {}) }) }), _jsx(TooltipContent, { children: label })] })) : (_jsx(Base.Trigger, { ref: triggerRef, id: id, "data-size": size, "aria-label": label, className: cn(FIELD, trigger === 'chip' && 'rounded-full', className), children: fieldInside })), _jsx("span", { ref: markRef, hidden: true }), popup] }));
 }
 /**
  * `trigger="none"`: the list anchored to a text box the page owns (the assistant @ and /). The text box

package/dist/lumen-view.js

@@ -269,9 +269,19 @@ export function LumenView({ domain, config, rows, total = rows.length, paging: s
     const pages = Math.max(1, Math.ceil(tableRows.length / pageSize));
     const page = Math.min(pageIndex, pages - 1);
     const count = rows.length === total ? `${total} rows` : `${rows.length} of ${total} rows`;
-    // A new filter or page size starts from the first page.
+    // The page holds while rows change in place (a tick, a label edit, a refresh, a bulk apply): only
+    // a new filter (a different set of rows), grouping, sort or page size starts from the first page.
+    // A page past the end after rows go is clamped above (`page`).
+    const rowSet = useMemo(() => rows
+        .map((r) => domain.rowKey(r))
+        .sort()
+        .join('\u0000'), [rows, domain]);
     // biome-ignore lint/correctness/useExhaustiveDependencies: resets on these changes only
-    useEffect(() => setPageIndex(0), [rows, pageSize]);
+    useEffect(() => setPageIndex(0), [rowSet, pageSize, groupBy?.key, sort?.key, sort?.desc]);
+    const sorted = (s) => {
+        setPageIndex(0);
+        onSort?.(s);
+    };
     // Checked rows with a chart symbol open one compare chart (up to 8).
     const openChart = useSymbolChart();
     const chartField = domain.fields.find((f) => f.chart);
@@ -291,7 +301,7 @@ export function LumenView({ domain, config, rows, total = rows.length, paging: s
     // A server's page: the pager counts from the server's total, or the rows seen so far. Server
     // groups page themselves: the header counts them.
     const pager = served?.pages ? (_jsx(LumenPager, { total: served.pages.total ?? served.pages.page * served.pages.size + (served.list?.length ?? 0), page: served.pages.page, size: served.pages.size, onPage: served.pages.onPage, onSize: served.pages.onSize ?? (() => { }), sizes: served.pages.sizes ?? [served.pages.size], noun: served.pages.noun ?? 'groups', more: served.pages.total === null && served.pages.more })) : served ? (_jsx("span", { className: "num px-2 text-xs text-muted-foreground", children: served.list ? `${served.list.length.toLocaleString()}${served.more ? '+' : ''} groups` : '' })) : server ? (_jsx(LumenPager, { total: server.total ?? server.page * server.size + rows.length, page: server.page, size: server.size, onPage: server.onPage, onSize: server.onSize ?? (() => { }), sizes: server.sizes ?? [server.size], more: server.total === null && server.more })) : paging ? (_jsx(LumenPager, { total: tableRows.length, page: page, size: pageSize, onPage: setPageIndex, onSize: setPageSize, noun: rows.length === total ? 'rows' : `of ${total} rows` })) : (_jsx("span", { className: "num px-2 text-xs text-muted-foreground", children: count }));
-    const table = pivot && config.pivot ? (_jsx(PivotTable, { domain: domain, rows: rows, pivot: config.pivot })) : (_jsx(LumenTable, { domain: domain, columns: columns, rows: tableRows, groupBy: groupBy, subgroup: sub, chips: chips, page: paging ? { index: page, size: pageSize } : null, inView: inLayout, fit: fit, onDetails: onDetails, tapped: tapped, selection: selection, groupActions: groupActions, sort: sort, onSort: onSort, serverSorts: server ? (server.sorts ?? []) : undefined, serverGroups: served, total: config.total !== false, add: onAddColumn || onColumns
+    const table = pivot && config.pivot ? (_jsx(PivotTable, { domain: domain, rows: rows, pivot: config.pivot })) : (_jsx(LumenTable, { domain: domain, columns: columns, rows: tableRows, groupBy: groupBy, subgroup: sub, chips: chips, page: paging ? { index: page, size: pageSize } : null, inView: inLayout, fit: fit, onDetails: onDetails, tapped: tapped, selection: selection, groupActions: groupActions, sort: sort, onSort: sorted, serverSorts: server ? (server.sorts ?? []) : undefined, serverGroups: served, total: config.total !== false, add: onAddColumn || onColumns
             ? { ...onAddColumn, field: onColumns && { domain, columns, onColumns } }
             : undefined }));
     return (_jsx(LumenWidget, { id: cardId, kind: "table", style: "table", title: title, controls: controls, tools: state ? (tools) : (_jsxs(_Fragment, { children: [tools, compare, pager, onColumns && !onAddColumn && on('columns') && (_jsx(ColumnPicker, { domain: domain, columns: columns, onColumns: onColumns })), !pivot && on('download') && (_jsx(IconButton, { icon: DownloadIcon, label: "Download CSV", onClick: () => downloadCsv({

package/dist/pace.d.ts

@@ -21,6 +21,8 @@ export interface BurnRate {
     raw: number;
     /** Lone hot samples that were capped. */
     spikes: number;
+    /** The window's own total, before any spike was capped. */
+    total: number;
 }
 /**
  * The rate over `samples` (oldest first, complete periods only), each `per` hours long. `gauge`:
@@ -42,9 +44,17 @@ export interface Pace extends BurnRate {
     resetIn: number;
     /** The rate that lands exactly on the cap at reset (0 once there). */
     safe: number;
+    /** The window had too little use to project (below `minTotal`): no time to the cap. */
+    thin: boolean;
 }
-/** 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;
+/**
+ * When `used` reaches `cap` at `rate`, and where it stands when the cap resets in `resetIn` hours.
+ * A window whose use is under `minTotal` (default 0.1% of the cap) is `thin`: no projection, so a
+ * handful of operations never reads as a time to the cap. Already at the cap reads as at the cap.
+ */
+export declare function timeToCap(rate: BurnRate, used: number, cap: number, resetIn: number, { minTotal }?: {
+    minTotal?: 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). */

package/dist/pace.js

@@ -3,6 +3,9 @@
 // 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.
+// Where most samples are empty (median 0), a lone nonzero sample is that burst and counts as 0.
+// Too little use in the window (`minTotal`, by default 0.1% of the cap) gives no time to the cap:
+// three operations in a day say nothing about a million-a-month allowance.
 // `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. */
@@ -24,14 +27,16 @@ const median = (xs) => {
 export function burnRate(samples, { per = 1, gauge = false, damp = true } = {}) {
     const n = samples.length;
     if (!n)
-        return { rate: 0, raw: 0, spikes: 0 };
+        return { rate: 0, raw: 0, spikes: 0, total: 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 d = n > 1 ? (samples[n - 1] ?? 0) - (samples[0] ?? 0) : 0;
+        const r = n > 1 ? d / ((n - 1) * per) : 0;
+        return { rate: r, raw: r, spikes: 0, total: Math.abs(d) };
     }
     const total = samples.reduce((s, v) => s + v, 0);
+    // With a median of 0, any use is above it: a lone sample among empty ones is damped to 0.
     const cap = median(samples) * 3;
-    const hot = (i) => cap > 0 && i >= 0 && i < n && (samples[i] ?? 0) > cap;
+    const hot = (i) => i >= 0 && i < n && (samples[i] ?? 0) > cap;
     let kept = 0;
     let spikes = 0;
     for (let i = 0; i < n; i++) {
@@ -43,19 +48,26 @@ export function burnRate(samples, { per = 1, gauge = false, damp = true } = {})
             kept += samples[i] ?? 0;
     }
     const hours = n * per;
-    return { rate: kept / hours, raw: total / hours, spikes };
+    return { rate: kept / hours, raw: total / hours, spikes, total };
 }
-/** When `used` reaches `cap` at `rate`, and where it stands when the cap resets in `resetIn` hours. */
-export function timeToCap(rate, used, cap, resetIn) {
+/**
+ * When `used` reaches `cap` at `rate`, and where it stands when the cap resets in `resetIn` hours.
+ * A window whose use is under `minTotal` (default 0.1% of the cap) is `thin`: no projection, so a
+ * handful of operations never reads as a time to the cap. Already at the cap reads as at the cap.
+ */
+export function timeToCap(rate, used, cap, resetIn, { minTotal = cap * 0.001 } = {}) {
     const left = cap - used;
-    const eta = left <= 0 ? 0 : rate.rate > 0 ? left / rate.rate : Number.POSITIVE_INFINITY;
+    const thin = left > 0 && rate.total < minTotal;
+    const r = thin ? 0 : Math.max(rate.rate, 0);
+    const eta = left <= 0 ? 0 : r > 0 ? left / r : Number.POSITIVE_INFINITY;
     return {
         ...rate,
         eta,
-        atReset: cap > 0 ? (used + Math.max(rate.rate, 0) * resetIn) / cap : 0,
+        atReset: cap > 0 ? (used + r * resetIn) / cap : 0,
         hits: eta <= resetIn,
         resetIn,
         safe: left > 0 && resetIn > 0 ? left / resetIn : 0,
+        thin,
     };
 }
 /** `40m`, `2h 05m`, `29h`, `3 days`; `short` gives `2h`, `29h`, `3d` (a phone cell). */

package/dist/trend-value.d.ts

@@ -0,0 +1,43 @@
+export type TrendChange = 
+/** Both periods empty, or nothing to compare. */
+{
+    kind: 'none';
+}
+/** No visible change. */
+ | {
+    kind: 'flat';
+}
+/** A share of the earlier period (0.12 = +12%). */
+ | {
+    kind: 'pct';
+    ratio: number;
+}
+/** Past `max` times the earlier period. */
+ | {
+    kind: 'many';
+    up: boolean;
+}
+/** The earlier period is at or under `minBase`: the plain difference. */
+ | {
+    kind: 'abs';
+    delta: number;
+};
+/**
+ * How `now` compares with `prev`. `minBase`: the smallest earlier period a share is worked out
+ * from (in the values' own unit); `max`: the multiple from which it reads `>10×`.
+ */
+export declare function trendChange(now: number, prev: number, { minBase, max }?: {
+    minBase?: number;
+    max?: number;
+}): TrendChange;
+/**
+ * Draws a `trendChange`: `▲ 12%`, `▼ 8%`, `▲ >10×`, `▲ +3` (`format` writes the difference), `0%`
+ * muted when flat, a dash when there is nothing to compare.
+ */
+export declare function TrendValue({ change, format, title, className, }: {
+    change: TrendChange | null;
+    /** Writes a plain difference (without its sign). */
+    format?: (v: number) => string;
+    title?: string;
+    className?: string;
+}): import("react").JSX.Element;

package/dist/trend-value.js

@@ -0,0 +1,40 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// A change between two periods (this week against the last) that never misleads: a share only when
+// the earlier period is big enough to divide by, the plain difference (`▲ +3`) when it is tiny or
+// empty, and `▲ >10×` once the change is past ten times, never a five-digit percent.
+import { cn } from './lib/utils.js';
+/**
+ * How `now` compares with `prev`. `minBase`: the smallest earlier period a share is worked out
+ * from (in the values' own unit); `max`: the multiple from which it reads `>10×`.
+ */
+export function trendChange(now, prev, { minBase = 0, max = 10 } = {}) {
+    const delta = now - prev;
+    if (!now && !prev)
+        return { kind: 'none' };
+    if (prev <= minBase)
+        return delta ? { kind: 'abs', delta } : { kind: 'flat' };
+    const ratio = now / prev - 1;
+    if (now / prev >= max)
+        return { kind: 'many', up: true };
+    if (Math.round(ratio * 100) === 0)
+        return { kind: 'flat' };
+    return { kind: 'pct', ratio };
+}
+const minus = (s) => s.replace(/^-/, '−');
+/**
+ * Draws a `trendChange`: `▲ 12%`, `▼ 8%`, `▲ >10×`, `▲ +3` (`format` writes the difference), `0%`
+ * muted when flat, a dash when there is nothing to compare.
+ */
+export function TrendValue({ change, format = (v) => Math.round(v).toLocaleString('en-US'), title, className, }) {
+    if (!change || change.kind === 'none')
+        return _jsx("span", { className: cn('text-muted-foreground', className), children: "\u2014" });
+    if (change.kind === 'flat')
+        return (_jsx("span", { className: cn('num text-muted-foreground', className), title: title, children: "0%" }));
+    const up = change.kind === 'pct' ? change.ratio > 0 : change.kind === 'abs' ? change.delta > 0 : change.up;
+    const text = change.kind === 'pct'
+        ? `${Math.abs(Math.round(change.ratio * 100))}%`
+        : change.kind === 'many'
+            ? '>10×'
+            : `${up ? '+' : '−'}${minus(format(Math.abs(change.delta)))}`;
+    return (_jsxs("span", { className: cn('num whitespace-nowrap', className), title: title, children: [up ? '▲' : '▼', " ", text] }));
+}

package/package.json

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