@columenlabs/lumen-ui 0.1.55 → 0.1.57

package/README.md

@@ -81,6 +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). 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

@@ -24,6 +24,9 @@ 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 { 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

@@ -31,6 +31,9 @@ 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 { 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/pace.d.ts

@@ -0,0 +1,63 @@
+/** 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 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`:
+ * 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;
+    /** 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.
+ * 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). */
+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,132 @@
+// 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.
+// 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. */
+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, total: 0 };
+    if (gauge) {
+        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) => 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, total };
+}
+/**
+ * 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 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 + 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). */
+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/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/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.55",
+  "version": "0.1.57",
   "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.55",
+    "@columenlabs/lumen-ui-types": "0.1.57",
     "@dnd-kit/core": "6.3.1",
     "@dnd-kit/sortable": "10.0.0",
     "@dnd-kit/utilities": "3.2.2",