@columenlabs/lumen-ui 0.1.50 → 0.1.52

package/README.md

@@ -78,6 +78,7 @@ Every export, its props and an example are on the [docs](https://lumen.columenla
 - 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.
 - 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/details-table.d.ts

@@ -1,10 +1,12 @@
 import type { ReactNode } from 'react';
 export interface DetailsTableProps {
-    /** `grow` marks the column that takes the spare width; the last column does by default. */
+    /** `grow` marks the column that takes the spare width; the last column does by default.
+     *  `hideOnPhone` drops a column on a phone, so the rest fit without scrolling sideways. */
     head: {
         label: string;
         right?: boolean;
         grow?: boolean;
+        hideOnPhone?: boolean;
     }[];
     rows: {
         key: string;

package/dist/details-table.js

@@ -4,8 +4,8 @@ import { Table, TableBody, TableCell, TableFooter, TableHead, TableHeader, Table
 export function DetailsTable({ head, rows, foot, selected, onSelect }) {
     const marked = head.findIndex((h) => h.grow);
     const grow = marked >= 0 ? marked : head.length - 1;
-    const cell = (i) => cn('num', head[i]?.right && 'text-right', i !== grow && 'w-px');
-    return (_jsx("div", { className: "-mx-1 overflow-x-auto overflow-y-hidden rounded-md border", children: _jsxs(Table, { children: [_jsx(TableHeader, { children: _jsx(TableRow, { children: head.map((h, i) => (_jsx(TableHead, { className: cn(h.right && 'text-right', i !== grow && 'w-px'), children: h.label }, h.label))) }) }), _jsx(TableBody, { children: rows.map((r) => (_jsx(TableRow, { "data-state": r.key === selected ? 'selected' : undefined, "aria-current": r.key === selected || undefined, tabIndex: onSelect ? 0 : undefined, className: cn(onSelect &&
+    const cell = (i) => cn('num', head[i]?.right && 'text-right', i !== grow && 'w-px', head[i]?.hideOnPhone && 'max-md:hidden');
+    return (_jsx("div", { className: "-mx-1 overflow-x-auto overflow-y-hidden rounded-md border", children: _jsxs(Table, { children: [_jsx(TableHeader, { children: _jsx(TableRow, { children: head.map((h, i) => (_jsx(TableHead, { className: cn(h.right && 'text-right', i !== grow && 'w-px', h.hideOnPhone && 'max-md:hidden'), children: h.label }, h.label))) }) }), _jsx(TableBody, { children: rows.map((r) => (_jsx(TableRow, { "data-state": r.key === selected ? 'selected' : undefined, "aria-current": r.key === selected || undefined, tabIndex: onSelect ? 0 : undefined, className: cn(onSelect &&
                             'cursor-pointer focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-ring'), onClick: onSelect && (() => onSelect(r.key)), onKeyDown: onSelect &&
                             ((e) => {
                                 if (e.key !== 'Enter' && e.key !== ' ')

package/dist/index.d.ts

@@ -22,6 +22,7 @@ export { LumenChoice, type LumenChoiceOption } from './lumen-choice.js';
 export { LumenSecret } from './lumen-secret.js';
 export { RankedBars, StackedBars, StackedColumns } from './lumen-widget-charts.js';
 export { ShareMeter } from './share-meter.js';
+export { METER_LEVEL_COLOR, meterLevel, meterValueTone } from './meter-level.js';
 export { UnitValue } from './unit-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';

package/dist/index.js

@@ -29,6 +29,7 @@ export { LumenChoice } from './lumen-choice.js';
 export { LumenSecret } from './lumen-secret.js';
 export { RankedBars, StackedBars, StackedColumns } from './lumen-widget-charts.js';
 export { ShareMeter } from './share-meter.js';
+export { METER_LEVEL_COLOR, meterLevel, meterValueTone } from './meter-level.js';
 export { UnitValue } from './unit-value.js';
 export { COVERAGE_LEVELS, CoverageCell, CoverageLegend, coverageClass, coverageLabel, coverageLevel, } from './coverage-cells.js';
 export { LumenCoverageMap, blockName, blockOf, } from './coverage-map.js';

package/dist/kit-config.d.ts

@@ -1,3 +1,4 @@
+import { type MeterLevels } from '@columenlabs/lumen-ui-types/views';
 import type { Prefs } from './prefs.js';
 export interface KitConfig {
     /** The cookie that keeps each person's display preferences. */
@@ -8,9 +9,13 @@ export interface KitConfig {
     marketOff: string;
     /** The app's own defaults for preferences a person has not set (theme, time zone, ...). */
     defaultPrefs?: Partial<Prefs>;
+    /** Where every meter turns amber (`watch`) and red (`alert`), as shares of a cap (0 to 1). */
+    meterLevels: MeterLevels;
 }
 export declare const KIT: KitConfig;
 /** Runs `fn` after each `configureLumen` (preferences read again from the app's cookie). */
 export declare function onConfigure(fn: () => void): void;
-/** Sets what `c` names; the rest keep the kit's defaults. */
-export declare function configureLumen(c: Partial<KitConfig>): void;
+/** Sets what `c` names; the rest keep the kit's defaults (one meter level can move alone). */
+export declare function configureLumen(c: Partial<Omit<KitConfig, 'meterLevels'>> & {
+    meterLevels?: Partial<MeterLevels>;
+}): void;

package/dist/kit-config.js

@@ -1,15 +1,23 @@
+// What an app tells the kit about itself (the kit is product-neutral): where
+// people's display preferences live and the line a market widget shows where the app has no feed.
+// Set once at start with `configureLumen`. The assistant's name comes from its provider.
+import { METER_LEVELS } from '@columenlabs/lumen-ui-types/views';
 export const KIT = {
     prefsCookie: 'lumen_prefs',
     marketOff: 'Live market data is not on this app.',
+    meterLevels: METER_LEVELS,
 };
 const changed = new Set();
 /** Runs `fn` after each `configureLumen` (preferences read again from the app's cookie). */
 export function onConfigure(fn) {
     changed.add(fn);
 }
-/** Sets what `c` names; the rest keep the kit's defaults. */
+/** Sets what `c` names; the rest keep the kit's defaults (one meter level can move alone). */
 export function configureLumen(c) {
-    Object.assign(KIT, c);
+    const { meterLevels, ...rest } = c;
+    Object.assign(KIT, rest);
+    if (meterLevels)
+        KIT.meterLevels = { ...KIT.meterLevels, ...meterLevels };
     for (const fn of changed)
         fn();
 }

package/dist/meter-level.d.ts

@@ -0,0 +1,7 @@
+import type { MeterLevel, MeterLevels } from '@columenlabs/lumen-ui-types/views';
+/** The level of `share` (0 to 1 of a cap), on the app's levels or this meter's own `levels`. */
+export declare function meterLevel(share: number, levels?: Partial<MeterLevels>): MeterLevel;
+/** Each level's colour, theme tokens: `ok` is a quiet grey so only a meter near its cap draws the eye. */
+export declare const METER_LEVEL_COLOR: Record<MeterLevel, string>;
+/** A share's `UnitValue` tone: none while `ok`. */
+export declare const meterValueTone: (share: number, levels?: Partial<MeterLevels>) => "loss" | "warning" | undefined;

package/dist/meter-level.js

@@ -0,0 +1,14 @@
+import { KIT } from './kit-config.js';
+/** The level of `share` (0 to 1 of a cap), on the app's levels or this meter's own `levels`. */
+export function meterLevel(share, levels) {
+    const { watch, alert } = { ...KIT.meterLevels, ...levels };
+    return share >= alert ? 'alert' : share >= watch ? 'watch' : 'ok';
+}
+/** Each level's colour, theme tokens: `ok` is a quiet grey so only a meter near its cap draws the eye. */
+export const METER_LEVEL_COLOR = {
+    ok: 'color-mix(in oklab, var(--muted-foreground) 55%, transparent)',
+    watch: 'var(--warning)',
+    alert: 'var(--loss)',
+};
+/** A share's `UnitValue` tone: none while `ok`. */
+export const meterValueTone = (share, levels) => ({ ok: undefined, watch: 'warning', alert: 'loss' })[meterLevel(share, levels)];

package/dist/share-meter.d.ts

@@ -1,11 +1,14 @@
+import type { MeterLevels } from '@columenlabs/lumen-ui-types/views';
 import type { ReactNode } from 'react';
-export declare function ShareMeter({ value, label, color, wide, className, }: {
+export declare function ShareMeter({ value, label, color, levels, wide, className, }: {
     /** 0 to 1 fills the bar; past 1 it stays full. */
     value: number;
     /** The number beside the bar, e.g. `113%`; left out, the rounded percent. */
     label?: ReactNode;
-    /** The bar's colour, a theme token (`var(--loss)` when over). */
+    /** The bar's colour, a theme token; left out, the share's level (grey, amber, red). */
     color?: string;
+    /** This meter's own levels (e.g. `{ watch: 0.5 }`); left out, the app's `meterLevels`. */
+    levels?: Partial<MeterLevels>;
     /** Fills its cell (a list row) instead of the fixed table width. */
     wide?: boolean;
     className?: string;

package/dist/share-meter.js

@@ -1,6 +1,9 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cn } from './lib/utils.js';
+import { METER_LEVEL_COLOR, meterLevel } from './meter-level.js';
 import { Progress } from './ui/progress.js';
-export function ShareMeter({ value, label, color = 'var(--primary)', wide, className, }) {
-    return (_jsxs("span", { className: cn('inline-flex items-center gap-2', wide && 'w-full', className), children: [_jsx(Progress, { value: Math.max(0, Math.min(value, 1)) * 100, className: cn('h-1.5 shrink-0 [&>[data-slot=progress-indicator]]:bg-(--meter-color)', wide ? 'w-full shrink' : 'w-14'), style: { '--meter-color': color } }), _jsx("span", { className: "num w-11 shrink-0 text-right text-xs", children: label ?? `${Math.round(value * 100)}%` })] }));
+export function ShareMeter({ value, label, color, levels, wide, className, }) {
+    return (_jsxs("span", { className: cn('inline-flex items-center gap-2', wide && 'w-full', className), children: [_jsx(Progress, { value: Math.max(0, Math.min(value, 1)) * 100, className: cn('h-1.5 shrink-0 [&>[data-slot=progress-indicator]]:bg-(--meter-color)', wide ? 'w-full shrink' : 'w-14'), style: {
+                    '--meter-color': color ?? METER_LEVEL_COLOR[meterLevel(value, levels)],
+                } }), _jsx("span", { className: "num w-11 shrink-0 text-right text-xs", children: label ?? `${Math.round(value * 100)}%` })] }));
 }

package/dist/summary-cards.js

@@ -15,6 +15,7 @@ import { useEffect, useMemo, useState } from 'react';
 import { PolarAngleAxis, RadialBar, RadialBarChart } from 'recharts';
 import { LumenConfirm } from './confirm.js';
 import { IconButton } from './icon-button.js';
+import { KIT } from './kit-config.js';
 import { cn } from './lib/utils.js';
 import { LumenTokenizedFilter, filterByTokens, useLumenFilter, } from './lumen-filter.js';
 import { LumenSelector } from './lumen-selector.js';
@@ -103,12 +104,17 @@ export function LumenCard({ domain, tile: t, rows, fields, drawn, loading, style
     const share = style !== 'number' && target && typeof v === 'number'
         ? Math.max(0, Math.min(100, (v / target) * 100))
         : null;
-    const tone = meterTone(meter, share, bands);
+    const tone = meterTone(meter, share, bands ?? (meter === 'usage' ? usageBands() : undefined));
     const of = target ? (_jsx(ViewValueCell, { value: target, format: figs.main.format, amount: figs.main.amount })) : null;
     if (style === 'progress_circle')
         return (_jsxs("div", { className: "flex min-w-0 items-center gap-3", children: [_jsx(ProgressRing, { value: share, tone: tone }), _jsxs("div", { className: "flex min-w-0 flex-col gap-0.5", children: [_jsx("span", { className: "num truncate text-xl leading-7 font-semibold", children: _jsx(FigureText, { f: figs.main }) }), _jsx("span", { className: "num truncate text-xs text-muted-foreground", children: of ? _jsxs(_Fragment, { children: ["of ", of] }) : 'Set a target in Edit widget' })] })] }));
     return (_jsxs("div", { className: "flex min-w-0 flex-col gap-0.5", children: [_jsx("span", { className: cn('num truncate text-2xl leading-8 font-semibold', t.sign && typeof v === 'number' && (v > 0 ? 'text-gain' : v < 0 ? 'text-loss' : '')), children: _jsx(FigureText, { f: figs.main }) }), style === 'progress_bar' && (_jsxs("div", { className: "flex flex-col gap-1 pt-1", children: [_jsx(Progress, { value: share ?? 0, className: cn('h-2', tone && TONE_BAR[tone]), "aria-label": "Progress to target" }), _jsx("span", { className: "num text-xs text-muted-foreground", children: of ? (_jsxs(_Fragment, { children: [share === null ? '—' : `${share.toFixed(0)}%`, " of ", of] })) : ('Set a target in Edit widget') })] })), figs.lines.map((l, i) => (_jsx("span", { className: "num line-clamp-2 text-xs text-muted-foreground", children: _jsx(FigureText, { f: l }) }, i)))] }));
 }
+/** A usage meter's bands from the app's `meterLevels`, in %. */
+const usageBands = () => ({
+    warn: KIT.meterLevels.watch * 100,
+    bad: KIT.meterLevels.alert * 100,
+});
 /** A meter's tone on a bar's fill (theme tokens, no glow). */
 const TONE_BAR = {
     success: '[&>[data-slot=progress-indicator]]:bg-success',

package/dist/unit-value.d.ts

@@ -1,11 +1,16 @@
+import type { MeterLevels } from '@columenlabs/lumen-ui-types/views';
 import type { ReactNode } from 'react';
-export declare function UnitValue({ value, unit, tone, title, className, }: {
+export declare function UnitValue({ value, unit, tone: toneProp, share, levels, title, className, }: {
     /** The number, already formatted (`231.4`). */
     value: ReactNode;
     /** Its unit (`GB`, `M`, `/day`); left out, the slot stays empty so the column still lines up. */
     unit?: ReactNode;
     /** Near (`warning`) or past (`loss`) a limit: tints the number and shows a dot. */
     tone?: 'warning' | 'loss';
+    /** Its share of a cap (0 to 1): sets `tone` by `meterLevel` (amber from 75%, red from 90%). */
+    share?: number;
+    /** This value's own levels; left out, the app's `meterLevels`. */
+    levels?: Partial<MeterLevels>;
     title?: string;
     className?: string;
 }): import("react").JSX.Element;

package/dist/unit-value.js

@@ -1,5 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cn } from './lib/utils.js';
-export function UnitValue({ value, unit, tone, title, className, }) {
+import { meterValueTone } from './meter-level.js';
+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') })] }));
 }

package/package.json

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