@columenlabs/lumen-ui 0.1.58 → 0.1.60

package/README.md

@@ -80,6 +80,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.
+- A shared cap split by who used it (an account's allowance by label): `ShareMeter segments={[{ value, color, label }]}` stacks each part's share of the cap in its own colour on the same fixed track; past the cap the track reads as the total and a tick marks the cap. Roll such rows up with `poolShare(rows, { pool, used, cap })` in a field's `rollRender`: a pool's share is its rows' use over the cap (never a sum or max of their own %), and a group across several pools reads the fullest one (`top`).
 - 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.

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { type CustomViewConfig, LumenTable, type LumenTableProps, LumenView, type LumenViewProps, type ServerGroup, type ServerGroups, type ServerPaging, type ViewCellValue, type ViewChipTone, type ViewDomain, type ViewField, type ViewFieldGroup, type ViewSource, CHIP_TONE, RUN_STATE_TONE, FORMULAS_GROUP, ViewValueCell, rollUp, } from './lumen-view.js';
+export { type CustomViewConfig, LumenTable, type LumenTableProps, LumenView, type LumenViewProps, type ServerGroup, type ServerGroups, type ServerPaging, type ViewCellValue, type ViewChipTone, type ViewDomain, type ViewField, type RollLevel, type ViewFieldGroup, type ViewSource, CHIP_TONE, RUN_STATE_TONE, FORMULAS_GROUP, ViewValueCell, rollUp, } from './lumen-view.js';
 export { LumenLayout, type LumenLayoutCard, type LumenLayoutProps, type LumenLayoutViewProps, domainKeys, followRows, } from './lumen-layout.js';
 export { LumenViewCard, type LumenViewCardProps } from './lumen-view-card.js';
 export { LumenSelector, LumenSelectorList, type LumenSelectorListHandle, type LumenSelectorProps, type LumenOption, type LumenOptionGroup, SelectorRowContent, } from './lumen-selector.js';
@@ -21,7 +21,8 @@ export { LumenDateInput, type LumenDateInputProps, stepDate, } from './lumen-dat
 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 { type ShareSegment, ShareMeter } from './share-meter.js';
+export { type Pool, poolShare } from './pool-share.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';

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 { poolShare } from './pool-share.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';

package/dist/lumen-view.d.ts

@@ -4,7 +4,7 @@ import { type ReactNode } from 'react';
 import { type LumenLoad } from './lumen-source.js';
 import { type CardControls, type CardLink } from './lumen-widget.js';
 import { type ViewCellValue, type ViewChipTone, type ViewDomain, type ViewField, type ViewSubgroup } from './view-model.js';
-export type { ViewCellValue, ViewChipTone, ViewDomain, ViewField, ViewFieldGroup, ViewSource, } from './view-model.js';
+export type { ViewCellValue, ViewChipTone, ViewDomain, ViewField, RollLevel, ViewFieldGroup, ViewSource, } from './view-model.js';
 export { CHIP_TONE, FORMULAS_GROUP, RUN_STATE_TONE } from './view-model.js';
 export { rollUp } from './view-model.js';
 export type { ViewEditorSection } from './view-editor.js';

package/dist/lumen-view.js

@@ -422,10 +422,14 @@ function LumenTableRows({ domain, columns = domain.fields, rows, groupBy = null,
     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.
+    // Under a sub-group's `flat` grouping each row names itself by its sub-group key instead of
+    // folding; the first column keeps its place to show that name.
+    const flat = !!groupBy && !!subgroup?.flat?.includes(groupBy.key);
+    // The grouped field is the group row's label, so its column hides (a flat lead stays).
     // Each key once: two columns under one React key can lose a cell on a re-render, and every
     // row after it slides left by one.
-    const visible = columns.filter((f, i) => f.key !== groupBy?.key && columns.findIndex((x) => x.key === f.key) === i);
+    const visible = columns.filter((f, i) => (f.key !== groupBy?.key || (flat && i === 0)) &&
+        columns.findIndex((x) => x.key === f.key) === i);
     // Inline chips sit on the first column, next to the row's name, not in their own.
     const inline = visible.filter((f, i) => i > 0 && chips.some((c) => c.key === f.key && c.placement === 'inline'));
     const shown = visible.filter((f) => !inline.includes(f));
@@ -506,7 +510,7 @@ function LumenTableRows({ domain, columns = domain.fields, rows, groupBy = null,
         },
         sortUndefined: 'last',
         enableSorting: !serverSorts || serverSorts.includes(f.key),
-        header: f.label,
+        header: i === 0 && flat && subgroup ? subgroup.label : f.label,
         cell: ({ row }) => {
             const { shown: now, cellOf, inline, chips, computed } = latest.current;
             const field = now[i] ?? f;
@@ -519,7 +523,7 @@ function LumenTableRows({ domain, columns = domain.fields, rows, groupBy = null,
                         return [{ key: x.key, node: cellOf(x, row.original, true) }];
                     }) })) : (cellOf(field, row.original, chip)) }));
         },
-    })), [shownKeys, inlineOn, serverSorts?.join(',')]);
+    })), [shownKeys, inlineOn, serverSorts?.join(','), flat]);
     const table = useTable({
         features: SORTING,
         data: rows,
@@ -585,7 +589,12 @@ function LumenTableRows({ domain, columns = domain.fields, rows, groupBy = null,
     const allOn = allKeys.length > 0 && allKeys.every((k) => selection?.keys.has(k));
     const someOn = allKeys.some((k) => selection?.keys.has(k));
     const selectCell = (key, name) => selection && (_jsx(TableCell, { className: "w-8 pr-0", onClick: (e) => e.stopPropagation(), children: _jsx(Checkbox, { checked: selection.keys.has(key), onCheckedChange: (on) => toggle([key], on === true), "aria-label": `Select ${name}` }) }));
-    const [openParts, setOpenParts] = useState(new Set());
+    // The rows whose open state the person flipped: a sub-group that starts open (`open`) lists
+    // the closed ones, any other the open ones.
+    const [partFlips, setOpenParts] = useState(new Set());
+    const openParts = {
+        has: (k) => (subgroup?.open && !domain.panel ? !partFlips.has(k) : partFlips.has(k)),
+    };
     // A server group's roll-ups would add up its loaded rows only, so they and the Total stay off.
     const hasTotal = total && !serverGroups && shown.some(rollsUp);
     // A group row's label spans the leading columns that roll nothing up.
@@ -596,15 +605,16 @@ function LumenTableRows({ domain, columns = domain.fields, rows, groupBy = null,
     // On a phone the hideOnPhone columns are gone, so the label spans only the leading ones still
     // 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, { ...col(f), children: rollCell(f, members) }, f.key)));
+    const rollCell = (f, members, level) => rollsUp(f) && f.rollRender ? (f.rollRender(members, level)) : 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, { ...col(f), children: rollCell(f, members, 'total') }, 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) ?? []));
     const panelOf = (row) => domain.panel?.render(row) ?? null;
     const opens = (row) => (domain.panel ? panelOf(row) !== null : partsOf(row).length > 1);
     const openLabel = () => domain.panel?.label ?? subgroup?.label.toLowerCase() ?? 'parts';
-    const folds = !domain.panel && !!subgroup?.under;
+    const folds = !domain.panel && !!subgroup?.under && !flat;
+    const flatName = (row) => flat && subgroup?.under ? (_jsxs("span", { className: "flex min-w-0 items-center gap-1.5", children: [subgroup.mark?.(subgroup.under(row), [row]), _jsx("span", { className: "truncate", children: subgroup.under(row) })] })) : null;
     const nests = folds || sorted.some((r) => opens(r.original));
     const chevron = (k, name) => (_jsx(Button, { variant: "ghost", size: "icon-xs", className: "-ml-1", "aria-expanded": openParts.has(k), "aria-label": `${openParts.has(k) ? 'Hide' : 'Show'} ${name}`, onClick: (e) => {
             e.stopPropagation();
@@ -627,14 +637,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, { ...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)) &&
+                    : 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())] })) : i === 0 && flat ? (flatName(r.original)) : (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, { ...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));
+        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()}`), subgroup?.mark?.(key, ms), _jsx("span", { className: "font-medium", children: key }), _jsx("span", { className: "num text-xs text-muted-foreground", children: ms.length })] })) : (rollCell(f, ms, 'fold')) }, f.key)))] }), openParts.has(k) && ms.map((p) => partRow(p, subgroup?.name))] }, k));
     };
     const rowsOf = (list, scope) => {
         const under = folds ? subgroup?.under : undefined;
@@ -701,10 +711,10 @@ function LumenTableRows({ domain, columns = domain.fields, rows, groupBy = null,
                                                                         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
+                                                                    }), children: [_jsx(ChevronRightIcon, { className: cn('transition-transform', open && 'rotate-90') }), _jsx(GroupMark, { field: groupBy, value: key }), 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));
+                                                            rollCell(f, members.map((m) => m.original), 'group') }, 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))] }))] })] }) }) }));
 }
@@ -733,3 +743,14 @@ function PivotTable({ domain, rows, pivot, }) {
     const amount = pivot.agg !== 'count' && vf.amount;
     return (_jsx("div", { className: IN_VIEW, "data-testid": "view-pivot", children: _jsxs(Table, { children: [_jsx(TableHeader, { children: _jsxs(TableRow, { children: [_jsx(TableHead, { className: PINNED_HEAD, style: ruleOf(colorOf(domain, rf)), children: _jsxs("span", { className: "flex items-center gap-1.5", children: [_jsx(rf.icon, { className: "size-3.5" }), _jsx("span", { style: { color: colorOf(domain, rf) ?? undefined }, children: rf.label }), " \\", ' ', _jsx("span", { style: { color: colorOf(domain, cf) ?? undefined }, children: cf.label }), _jsxs("span", { className: "font-normal text-muted-foreground", children: ["(", _jsx("span", { style: { color: colorOf(domain, vf) ?? undefined }, children: vf.label }), ",", ' ', pivot.agg, ")"] })] }) }), grid.colKeys.map((c) => (_jsx(TableHead, { className: cn('text-right', PINNED_HEAD), style: ruleOf(colorOf(domain, cf)), children: c }, c))), totals && _jsx(TableHead, { className: cn('text-right', PINNED_HEAD), children: "Total" })] }) }), _jsxs(TableBody, { children: [grid.rowKeys.map((r) => (_jsxs(TableRow, { "data-row": r, children: [_jsx(TableCell, { children: r }), grid.colKeys.map((c) => (_jsx(TableCell, { className: "text-right", children: _jsx(ViewValueCell, { value: grid.cell(r, c), format: fmt, amount: amount }) }, c))), totals && (_jsx(TableCell, { className: cn('text-right', ROLLUP), children: _jsx(ViewValueCell, { value: grid.cell(r, null), format: fmt, amount: amount }) }))] }, r))), totals && (_jsxs(TableRow, { className: cn(ROLLUP, 'border-t-2'), "data-total": true, children: [_jsx(TableCell, { children: "Total" }), grid.colKeys.map((c) => (_jsx(TableCell, { className: "text-right", children: _jsx(ViewValueCell, { value: grid.cell(null, c), format: fmt, amount: amount }) }, c))), _jsx(TableCell, { className: "text-right", children: _jsx(ViewValueCell, { value: grid.cell(null, null), format: fmt, amount: amount }) })] }))] })] }) }));
 }
+/** A group heading's mark: its value's icon in its colour, else its colour's dot, else the
+ *  field's icon. */
+function GroupMark({ field, value }) {
+    const color = field.color?.(value);
+    const Icon = field.iconOf?.(value);
+    if (Icon)
+        return (_jsx("span", { className: "inline-flex", style: color ? { color } : undefined, children: _jsx(Icon, { className: "size-3.5" }) }));
+    if (color)
+        return _jsx(ColorDot, { color: color });
+    return _jsx(field.icon, {});
+}

package/dist/pool-share.d.ts

@@ -0,0 +1,22 @@
+export interface Pool<T> {
+    key: string;
+    used: number;
+    cap: number;
+    /** `used / cap`; 0 when the pool has no cap (pay as you go). */
+    share: number;
+    rows: T[];
+}
+/**
+ * The pools `rows` fall in and the fullest one's share. `cap` is read from each pool's first row
+ * (every row of a pool shares it); a cap of 0 or less has no share. Use it in a field's
+ * `rollRender`, so a group or Total row reads the share again from its rows.
+ */
+export declare function poolShare<T>(rows: T[], by: {
+    pool: (row: T) => string;
+    used: (row: T) => number;
+    cap: (row: T) => number;
+}): {
+    share: number;
+    top: Pool<T> | null;
+    pools: Pool<T>[];
+};

package/dist/pool-share.js

@@ -0,0 +1,24 @@
+// Rows that each use part of one shared cap (an account's allowance, split by label or resource)
+// roll up as the pool's use over that cap: never a sum or a max of the rows' own shares. A group
+// that spans several pools reads its fullest one, the cap it will hit first.
+/**
+ * The pools `rows` fall in and the fullest one's share. `cap` is read from each pool's first row
+ * (every row of a pool shares it); a cap of 0 or less has no share. Use it in a field's
+ * `rollRender`, so a group or Total row reads the share again from its rows.
+ */
+export function poolShare(rows, by) {
+    const m = new Map();
+    for (const r of rows) {
+        const key = by.pool(r);
+        const p = m.get(key) ?? { key, used: 0, cap: by.cap(r), share: 0, rows: [] };
+        p.used += by.used(r);
+        p.rows.push(r);
+        m.set(key, p);
+    }
+    const pools = [...m.values()];
+    for (const p of pools)
+        p.share = p.cap > 0 ? p.used / p.cap : 0;
+    pools.sort((a, b) => b.share - a.share);
+    const top = pools[0] ?? null;
+    return { share: top?.share ?? 0, top, pools };
+}

package/dist/share-meter.d.ts

@@ -1,7 +1,15 @@
 import type { MeterLevels } from '@columenlabs/lumen-ui-types/views';
 import type { ReactNode } from 'react';
-export declare function ShareMeter({ value, label, color, levels, wide, className, }: {
-    /** 0 to 1 fills the bar; past 1 it stays full. */
+/** One part of a split meter: its own share of the cap (0 to 1 of the whole cap), in its colour. */
+export interface ShareSegment {
+    value: number;
+    /** A theme token or CSS colour (a label's colour). */
+    color: string;
+    /** Who it is, read out by screen readers and in the bar's hover (`web 122%`). */
+    label?: string;
+}
+export declare function ShareMeter({ value, label, color, levels, segments, wide, className, }: {
+    /** 0 to 1 fills the bar; past 1 it stays full (with `segments`, the track stretches instead). */
     value: number;
     /** The number beside the bar, e.g. `113%`; left out, the rounded percent. */
     label?: ReactNode;
@@ -9,6 +17,8 @@ export declare function ShareMeter({ value, label, color, levels, wide, classNam
     color?: string;
     /** This meter's own levels (e.g. `{ watch: 0.5 }`); left out, the app's `meterLevels`. */
     levels?: Partial<MeterLevels>;
+    /** Splits the bar by who used the cap, largest first; their values add up to `value`. */
+    segments?: ShareSegment[];
     /** Fills its cell (a list row) instead of the fixed table width. */
     wide?: boolean;
     className?: string;

package/dist/share-meter.js

@@ -2,8 +2,17 @@ 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, levels, wide, className, }) {
+export function ShareMeter({ value, label, color, levels, segments, wide, className, }) {
+    const number = (_jsx("span", { className: "num w-11 shrink-0 text-right text-xs", children: label ?? `${Math.round(value * 100)}%` }));
+    if (segments?.length) {
+        // Past the cap the bar keeps its width: the track reads as the total and the tick as the cap.
+        const scale = Math.max(1, value);
+        const said = segments
+            .filter((s) => s.value > 0)
+            .map((s) => `${s.label ?? ''} ${Math.round(s.value * 100)}%`.trim());
+        return (_jsxs("span", { className: cn('inline-flex items-center gap-2', wide && 'w-full', className), children: [_jsxs("span", { role: "img", "aria-label": said.join(', '), title: said.join(' · '), "data-slot": "share-segments", className: cn('relative flex h-1.5 shrink-0 overflow-hidden rounded-full bg-muted', wide ? 'w-full shrink' : 'w-14'), children: [segments.map((s, i) => s.value > 0 ? (_jsx("span", { className: "h-full shrink-0 border-background not-first:border-l", style: { width: `${(s.value / scale) * 100}%`, background: s.color } }, i)) : null), value > 1 && (_jsx("span", { "aria-hidden": true, className: "absolute inset-y-0 w-0.5 -translate-x-1/2 bg-foreground/70", style: { left: `${(1 / scale) * 100}%` } }))] }), number] }));
+    }
     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)}%` })] }));
+                } }), number] }));
 }

package/dist/view-model.d.ts

@@ -98,9 +98,10 @@ export interface ViewField<T> {
     /**
      * Draws a group or Total row's cell from its rows instead of the rolled-up number: an amount with
      * its unit, or a share worked out again as the rows' total over their allowance (never a sum of
-     * percents). Only where the field rolls up (`aggregate`).
+     * percents). Only where the field rolls up (`aggregate`). `level` says which line it draws: a
+     * group heading, a sub-group's folded line or the Total (a split bar on a fold only).
      */
-    rollRender?: (rows: T[]) => ReactNode;
+    rollRender?: (rows: T[], level: RollLevel) => ReactNode;
     /**
      * Ways the column can read, picked per column in Edit view ("Show as"), e.g. an amount or its % of
      * an allowance. The first is the field as defined; each other one's `field` replaces those parts
@@ -123,7 +124,8 @@ export interface ViewField<T> {
      * cell, its chip and the edit picker. A CSS colour; a theme token reads in light and dark.
      */
     color?: (value: string) => string | undefined;
-    /** A text value's icon (a label's), drawn in its `color` on its chip and in the edit picker. */
+    /** A text value's icon (a label's, a product's), drawn in its `color` on its chip, in the edit
+     *  picker and on its group's heading. */
     iconOf?: (value: string) => ComponentType<{
         className?: string;
     }> | undefined;
@@ -300,6 +302,8 @@ export interface ViewDomain<T> {
 export declare const summaryCash: (card: {
     cash?: boolean;
 }, narrowed: boolean) => boolean;
+/** The line a `rollRender` draws: a group heading, a sub-group's folded line, the Total. */
+export type RollLevel = 'group' | 'fold' | 'total';
 /** One choice of a domain's "Each row opens". */
 export interface ViewSubgroup<T> {
     key: string;
@@ -310,6 +314,15 @@ export interface ViewSubgroup<T> {
     name?: (row: T) => string;
     /** `under` folds a key even when one row has it (a field's second level of grouping). */
     always?: boolean;
+    /** Rows start open, their parts showing (a meter's labels); a click still closes one. */
+    open?: boolean;
+    /** Drawn before a folded line's key (a meter's product icon, in its colour). */
+    mark?: (key: string, rows: T[]) => ReactNode;
+    /**
+     * Group fields under which rows do not fold: each row is one line named by its `under` key (and
+     * `mark`) instead of its first column (grouped by label, a label's meters).
+     */
+    flat?: string[];
 }
 /**
  * What a row can open: the domain's own sub-groups, else every groupable field as a second level

package/package.json

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