@makoai/app-sdk 2.14.1 → 2.15.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +34 -7
- package/index.js +6 -1
- package/package.json +1 -1
- package/ui-core.js +50 -9
- package/ui.css +6 -1
- package/ui.d.ts +41 -4
- package/ui.js +22 -4
package/README.md
CHANGED
|
@@ -391,17 +391,26 @@ import {
|
|
|
391
391
|
and declare it once (`src/vite-env.d.ts`):
|
|
392
392
|
`declare const __APP_BINDING_NAMES__: string[];`
|
|
393
393
|
|
|
394
|
-
### Chart tooltips: `TableTooltip` (2.10
|
|
394
|
+
### Chart tooltips: `TableTooltip` (2.10+, every series from 2.15)
|
|
395
395
|
|
|
396
396
|
Every chart tooltip is a table, never recharts' coloured `name : value` list:
|
|
397
397
|
a bold title, small muted column headers, one row per series with a 9px
|
|
398
398
|
swatch in the series colour and the label in plain text, right-aligned
|
|
399
399
|
tabular numbers, and a bold total row under a rule.
|
|
400
400
|
|
|
401
|
+
The tooltip lists every legend series, in legend order, in every bucket. Its
|
|
402
|
+
height and column widths never change while the pointer moves.
|
|
403
|
+
|
|
404
|
+
- A zero shows a muted "0", or a muted "0%" for a rate.
|
|
405
|
+
- A missing value shows a muted "–". Missing means the bucket has no data, or
|
|
406
|
+
the metric cannot be computed (a rate over a zero base).
|
|
407
|
+
- The value columns have a fixed minimum width (`--mk-tip-col`, default
|
|
408
|
+
`7ch`).
|
|
409
|
+
|
|
401
410
|
```tsx
|
|
402
|
-
import { tableTooltip, tooltipSeriesRows } from "@makoai/app-sdk/ui";
|
|
411
|
+
import { tableTooltip, tooltipCell, tooltipSeriesRows } from "@makoai/app-sdk/ui";
|
|
403
412
|
|
|
404
|
-
const SEGMENTS = [ // bottom-up, as stacked; drives the bars AND the tooltip
|
|
413
|
+
const SEGMENTS = [ // bottom-up, as stacked; drives the bars, the legend AND the tooltip
|
|
405
414
|
{ key: "new", label: "New", color: "var(--positive)" },
|
|
406
415
|
{ key: "churn", label: "Churn", color: "var(--negative)" },
|
|
407
416
|
];
|
|
@@ -411,16 +420,27 @@ const SEGMENTS = [ // bottom-up, as stacked; drives the bars AND the tooltip
|
|
|
411
420
|
title: d.month,
|
|
412
421
|
columns: ["MRR", "Orgs", "% of start"],
|
|
413
422
|
rows: tooltipSeriesRows(d, SEGMENTS, { stacked: true }).map((r) => ({
|
|
414
|
-
...r,
|
|
423
|
+
...r,
|
|
424
|
+
cells: [
|
|
425
|
+
tooltipCell(r.value, fmtEur),
|
|
426
|
+
tooltipCell(d[`orgs_${r.key}`], fmtInt),
|
|
427
|
+
tooltipCell(r.value == null || !d.start ? null : r.value / d.start, fmtPct, { percent: true }),
|
|
428
|
+
],
|
|
415
429
|
})),
|
|
416
430
|
total: { label: "Net change", cells: [fmtEur(d.net), fmtInt(d.netOrgs), fmtPct(d.net / d.start)] },
|
|
417
431
|
}))}
|
|
418
432
|
/>
|
|
419
433
|
```
|
|
420
434
|
|
|
421
|
-
- `tooltipSeriesRows(datum, series, { stacked })`
|
|
422
|
-
|
|
423
|
-
|
|
435
|
+
- `tooltipSeriesRows(datum, series, { stacked })` returns one row per series,
|
|
436
|
+
`{ key, label, color, value, state }`. A stack reads top segment first.
|
|
437
|
+
Other charts keep the series order, which is the legend order. `state` is
|
|
438
|
+
`"value"`, `"zero"` or `"missing"`. A missing `value` is `null`.
|
|
439
|
+
- `tooltipCell(value, format, { percent })` renders a cell: a muted "–" when
|
|
440
|
+
missing, a muted "0" or "0%" when zero, else `format(value)`.
|
|
441
|
+
`tooltipCellText` returns the same as `{ text, muted }` for non-React code.
|
|
442
|
+
- A `null` or `undefined` cell in `TableTooltip` shows a muted "–". An empty
|
|
443
|
+
string stays blank.
|
|
424
444
|
- `total` is the stack total, "All selected", or the base the % is of.
|
|
425
445
|
`after` rows follow it, apart: a value on another axis.
|
|
426
446
|
- Precompute what the tooltip shows (totals, counts, bases) in each data row.
|
|
@@ -428,6 +448,13 @@ const SEGMENTS = [ // bottom-up, as stacked; drives the bars AND the tooltip
|
|
|
428
448
|
- On a chart with an HTML overlay (a donut's centre label), lift the tooltip:
|
|
429
449
|
`<Tooltip wrapperStyle={{ zIndex: 20 }} … />`.
|
|
430
450
|
|
|
451
|
+
**Opt-out.** Before 2.15, `tooltipSeriesRows` dropped zero and missing values
|
|
452
|
+
and sorted line charts highest value first. A caller that truly needs that
|
|
453
|
+
passes `{ hideEmpty: true, byValue: true }`. `hideEmpty` drops zero and
|
|
454
|
+
missing rows. `byValue` sorts non-stacked rows highest first, missing last.
|
|
455
|
+
Both make the tooltip change height or order between buckets, so the house
|
|
456
|
+
rule is to leave them off.
|
|
457
|
+
|
|
431
458
|
### Data tables: `DataTable` (2.11+)
|
|
432
459
|
|
|
433
460
|
`DataTable` is the table the best workspace dashboards converged on: a card
|
package/index.js
CHANGED
|
@@ -36,7 +36,7 @@ import {
|
|
|
36
36
|
* in a page (or this export) says which SDK a deployed app actually runs.
|
|
37
37
|
* Kept in step with package.json by snapshot.test.mjs.
|
|
38
38
|
*/
|
|
39
|
-
export const SDK_VERSION = "2.
|
|
39
|
+
export const SDK_VERSION = "2.15.0";
|
|
40
40
|
if (typeof window !== "undefined") {
|
|
41
41
|
try {
|
|
42
42
|
window.__MAKO_APP_SDK__ = SDK_VERSION;
|
|
@@ -902,6 +902,11 @@ function startPressure() {
|
|
|
902
902
|
|
|
903
903
|
/** Pinned views come back on their own: a mounted panel may not read again soon. */
|
|
904
904
|
async function endPressure() {
|
|
905
|
+
// The timer, not the clock, ends pressure: a timer can fire a millisecond
|
|
906
|
+
// before Date.now() reaches pressureUntil, and roomForTable would then still
|
|
907
|
+
// see pressure and refuse every promotion, with nothing left to retry it.
|
|
908
|
+
pressureUntil = 0;
|
|
909
|
+
pressureTimer = null;
|
|
905
910
|
const waiting = [...entries]
|
|
906
911
|
.filter(([name, entry]) => entry.demoted && isPinned(name) && !loading.has(name))
|
|
907
912
|
.sort(([a], [b]) => (lastUse.get(b) ?? 0) - (lastUse.get(a) ?? 0));
|
package/package.json
CHANGED
package/ui-core.js
CHANGED
|
@@ -48,16 +48,57 @@ export function formatSeconds(s) {
|
|
|
48
48
|
}
|
|
49
49
|
|
|
50
50
|
/**
|
|
51
|
-
*
|
|
52
|
-
*
|
|
53
|
-
* order they are drawn), lines highest first. Empty (null, undefined, 0)
|
|
54
|
-
* values are left out. Returns `{ key, label, color, value }`.
|
|
51
|
+
* What a tooltip cell holds: "missing" (null, undefined, "", NaN, ±Infinity:
|
|
52
|
+
* no data, or a metric the bucket cannot compute), "zero", or "value".
|
|
55
53
|
*/
|
|
56
|
-
export function
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
return
|
|
54
|
+
export function tooltipValueState(v) {
|
|
55
|
+
if (v == null || v === "") return "missing";
|
|
56
|
+
const n = typeof v === "bigint" ? Number(v) : Number(v);
|
|
57
|
+
if (!Number.isFinite(n)) return "missing";
|
|
58
|
+
return n === 0 ? "zero" : "value";
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/**
|
|
62
|
+
* The rows a chart tooltip shows for one hovered datum: every series, in a
|
|
63
|
+
* fixed order, so the tooltip keeps its height and columns while the pointer
|
|
64
|
+
* moves. A stack reads top segment first (series are given bottom-up, the
|
|
65
|
+
* order they are drawn); other charts keep the series (legend) order. A zero
|
|
66
|
+
* stays as a row with `state: "zero"`; a missing value stays with
|
|
67
|
+
* `value: null` and `state: "missing"`. Render the cells with `tooltipCell`.
|
|
68
|
+
*
|
|
69
|
+
* Opt-outs, for a caller that truly needs the pre-2.15 behaviour:
|
|
70
|
+
* `hideEmpty: true` drops zero and missing rows; `byValue: true` sorts
|
|
71
|
+
* non-stacked rows highest value first (missing last).
|
|
72
|
+
* Returns `{ key, label, color, value, state }`.
|
|
73
|
+
*/
|
|
74
|
+
export function tooltipSeriesRows(datum, series, { stacked = false, hideEmpty = false, byValue = false } = {}) {
|
|
75
|
+
let rows = series.map(s => {
|
|
76
|
+
const raw = datum?.[s.key];
|
|
77
|
+
const state = tooltipValueState(raw);
|
|
78
|
+
return { key: s.key, label: s.label ?? s.key, color: s.color, value: state === "missing" ? null : Number(raw), state };
|
|
79
|
+
});
|
|
80
|
+
if (hideEmpty) rows = rows.filter(r => r.state === "value");
|
|
81
|
+
if (stacked) return rows.reverse();
|
|
82
|
+
if (!byValue) return rows;
|
|
83
|
+
return rows
|
|
84
|
+
.map((r, i) => ({ r, i }))
|
|
85
|
+
.sort((a, b) => {
|
|
86
|
+
if (a.r.value == null || b.r.value == null) return a.r.value == null ? (b.r.value == null ? a.i - b.i : 1) : -1;
|
|
87
|
+
return b.r.value - a.r.value || a.i - b.i;
|
|
88
|
+
})
|
|
89
|
+
.map(x => x.r);
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/**
|
|
93
|
+
* The text a tooltip value cell shows, and whether it is muted: a missing
|
|
94
|
+
* value → muted "–", a zero → muted "0" ("0%" with `percent`), else
|
|
95
|
+
* `format(value)`.
|
|
96
|
+
*/
|
|
97
|
+
export function tooltipCellText(value, format = String, { percent = false } = {}) {
|
|
98
|
+
const state = tooltipValueState(value);
|
|
99
|
+
if (state === "missing") return { text: "–", muted: true };
|
|
100
|
+
if (state === "zero") return { text: percent ? "0%" : "0", muted: true };
|
|
101
|
+
return { text: format(Number(value)), muted: false };
|
|
61
102
|
}
|
|
62
103
|
|
|
63
104
|
// ---------------------------------------------------------------------------
|
package/ui.css
CHANGED
|
@@ -174,7 +174,12 @@ button:not(:disabled), [role="button"]:not(:disabled) { cursor: pointer; }
|
|
|
174
174
|
.mk-tip table { border-collapse: collapse; }
|
|
175
175
|
.mk-tip thead th { color: var(--muted-foreground); font-weight: 500; text-align: right; padding-left: 12px; }
|
|
176
176
|
.mk-tip tbody th { text-align: left; font-weight: 400; padding-top: 2px; }
|
|
177
|
-
|
|
177
|
+
/* Value columns hold a fixed minimum width (override with --mk-tip-col), so
|
|
178
|
+
* the box never resizes while the pointer slides across the chart. */
|
|
179
|
+
.mk-tip td { text-align: right; padding: 2px 0 0 12px; font-variant-numeric: tabular-nums; min-width: var(--mk-tip-col, 7ch); }
|
|
180
|
+
.mk-tip thead th:not(:first-child) { min-width: var(--mk-tip-col, 7ch); }
|
|
181
|
+
/* A zero ("0", "0%") or a missing value ("–"): kept, but muted. */
|
|
182
|
+
.mk-tip-muted { color: var(--muted-foreground); font-weight: 400; }
|
|
178
183
|
.mk-tip-swatch { display: inline-block; width: 9px; height: 9px; border-radius: 2px; margin-right: 6px; }
|
|
179
184
|
.mk-tip-total th, .mk-tip-total td { font-weight: 600; }
|
|
180
185
|
.mk-tip-rule th, .mk-tip-rule td { border-top: 1px solid var(--border); padding-top: 3px; }
|
package/ui.d.ts
CHANGED
|
@@ -145,6 +145,7 @@ export interface TooltipRow {
|
|
|
145
145
|
label: React.ReactNode;
|
|
146
146
|
/** The series colour for the 9px swatch; omit for no swatch. */
|
|
147
147
|
color?: string;
|
|
148
|
+
/** A null or undefined cell shows a muted "–"; "" stays blank. */
|
|
148
149
|
cells: React.ReactNode[];
|
|
149
150
|
key?: string;
|
|
150
151
|
}
|
|
@@ -166,15 +167,51 @@ export function TableTooltip(props: TableTooltipProps): React.ReactElement;
|
|
|
166
167
|
export function tableTooltip<D = any>(
|
|
167
168
|
build: (datum: D, label: unknown) => TableTooltipProps | null,
|
|
168
169
|
): (props: { active?: boolean; payload?: readonly { payload?: unknown }[]; label?: unknown }) => React.ReactElement | null;
|
|
170
|
+
/** "missing" (null, undefined, "", NaN, ±Infinity), "zero" or "value". */
|
|
171
|
+
export type TooltipValueState = "missing" | "zero" | "value";
|
|
172
|
+
export function tooltipValueState(value: unknown): TooltipValueState;
|
|
173
|
+
export interface TooltipSeriesRow<K extends string = string> {
|
|
174
|
+
key: K;
|
|
175
|
+
label: string;
|
|
176
|
+
color?: string;
|
|
177
|
+
/** null when missing. */
|
|
178
|
+
value: number | null;
|
|
179
|
+
state: TooltipValueState;
|
|
180
|
+
}
|
|
181
|
+
export interface TooltipSeriesRowsOptions {
|
|
182
|
+
/** Pass series bottom-up, as drawn; the rows read top segment first. */
|
|
183
|
+
stacked?: boolean;
|
|
184
|
+
/** Opt-out: drop zero and missing rows (pre-2.15). Breaks the fixed tooltip height. */
|
|
185
|
+
hideEmpty?: boolean;
|
|
186
|
+
/** Opt-out: sort non-stacked rows highest value first, missing last (pre-2.15). */
|
|
187
|
+
byValue?: boolean;
|
|
188
|
+
}
|
|
169
189
|
/**
|
|
170
|
-
*
|
|
171
|
-
* (pass series bottom-up, as drawn), else
|
|
190
|
+
* Every series of the hovered datum, in a fixed order: stacked = top segment
|
|
191
|
+
* first (pass series bottom-up, as drawn), else legend (series) order. Zero
|
|
192
|
+
* and missing values keep their row; render the cells with `tooltipCell`.
|
|
172
193
|
*/
|
|
173
194
|
export function tooltipSeriesRows<K extends string>(
|
|
174
195
|
datum: Record<string, unknown> | null | undefined,
|
|
175
196
|
series: readonly { key: K; label?: string; color?: string }[],
|
|
176
|
-
opts?:
|
|
177
|
-
):
|
|
197
|
+
opts?: TooltipSeriesRowsOptions,
|
|
198
|
+
): TooltipSeriesRow<K>[];
|
|
199
|
+
export interface TooltipCellOptions {
|
|
200
|
+
/** A zero shows "0%" instead of "0". */
|
|
201
|
+
percent?: boolean;
|
|
202
|
+
}
|
|
203
|
+
/** A cell's text and whether it is muted (zero or missing). */
|
|
204
|
+
export function tooltipCellText(
|
|
205
|
+
value: unknown,
|
|
206
|
+
format?: (value: number) => string,
|
|
207
|
+
opts?: TooltipCellOptions,
|
|
208
|
+
): { text: string; muted: boolean };
|
|
209
|
+
/** A value cell: missing → muted "–", zero → muted "0" / "0%", else `format(value)`. */
|
|
210
|
+
export function tooltipCell(
|
|
211
|
+
value: unknown,
|
|
212
|
+
format?: (value: number) => string,
|
|
213
|
+
opts?: TooltipCellOptions,
|
|
214
|
+
): React.ReactNode;
|
|
178
215
|
|
|
179
216
|
/** A table sort: the column id and its direction. */
|
|
180
217
|
export interface DataTableSort {
|
package/ui.js
CHANGED
|
@@ -28,7 +28,9 @@ import {
|
|
|
28
28
|
serializeResetKey,
|
|
29
29
|
sortRows,
|
|
30
30
|
toCsv,
|
|
31
|
+
tooltipCellText,
|
|
31
32
|
tooltipSeriesRows,
|
|
33
|
+
tooltipValueState,
|
|
32
34
|
} from "./ui-core.js";
|
|
33
35
|
|
|
34
36
|
export {
|
|
@@ -47,7 +49,9 @@ export {
|
|
|
47
49
|
serializeResetKey,
|
|
48
50
|
sortRows,
|
|
49
51
|
toCsv,
|
|
52
|
+
tooltipCellText,
|
|
50
53
|
tooltipSeriesRows,
|
|
54
|
+
tooltipValueState,
|
|
51
55
|
};
|
|
52
56
|
|
|
53
57
|
const h = React.createElement;
|
|
@@ -246,16 +250,30 @@ function TooltipRow({ row, className }) {
|
|
|
246
250
|
h("span", { className: "mk-tip-swatch", style: { background: row.color ?? "transparent" } }),
|
|
247
251
|
row.label,
|
|
248
252
|
),
|
|
249
|
-
...(row.cells ?? []).map((c, i) => h("td", { key: i }, c)),
|
|
253
|
+
...(row.cells ?? []).map((c, i) => h("td", { key: i }, c == null ? MISSING_CELL : c)),
|
|
250
254
|
);
|
|
251
255
|
}
|
|
252
256
|
|
|
257
|
+
/** A missing value: no data in the bucket, or a metric it cannot compute. */
|
|
258
|
+
const MISSING_CELL = h("span", { className: "mk-tip-muted" }, "–");
|
|
259
|
+
|
|
260
|
+
/**
|
|
261
|
+
* A tooltip value cell: a missing value (null, undefined, NaN) → muted "–",
|
|
262
|
+
* a zero → muted "0" (or "0%" with `percent: true`), else `format(value)`.
|
|
263
|
+
* The row stays either way, so the tooltip never changes height.
|
|
264
|
+
*/
|
|
265
|
+
export function tooltipCell(value, format, opts) {
|
|
266
|
+
const { text, muted } = tooltipCellText(value, format, opts);
|
|
267
|
+
return muted ? h("span", { className: "mk-tip-muted" }, text) : text;
|
|
268
|
+
}
|
|
269
|
+
|
|
253
270
|
/**
|
|
254
271
|
* The house chart tooltip: a bold title, small muted column headers, one row
|
|
255
272
|
* per series with a 9px swatch in the series colour and the label in the
|
|
256
|
-
* popover's text colour, right-aligned tabular numbers
|
|
257
|
-
* row under a rule. `after` rows follow
|
|
258
|
-
* axis, such as an average next to a
|
|
273
|
+
* popover's text colour, right-aligned tabular numbers in columns of a fixed
|
|
274
|
+
* minimum width, then a bold `total` row under a rule. `after` rows follow
|
|
275
|
+
* the total, apart (a value on another axis, such as an average next to a
|
|
276
|
+
* rate). A null or undefined cell shows a muted "–"; "" stays blank.
|
|
259
277
|
*/
|
|
260
278
|
export function TableTooltip({ title, columns = [], rows = [], total, after, className }) {
|
|
261
279
|
return h(
|