@makoai/app-sdk 2.14.2 → 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 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, cells: [fmtEur(r.value), fmtInt(d[`orgs_${r.key}`]), fmtPct(r.value / d.start)],
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 })` puts the rows in reading
422
- order (a stack's top segment first, lines highest first) and drops empty
423
- values.
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.14.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;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@makoai/app-sdk",
3
- "version": "2.14.2",
3
+ "version": "2.15.0",
4
4
  "description": "Mako app SDK: data bindings (useQuery/useDuckDB), URL state, theme, and the house dashboard kit (/ui).",
5
5
  "license": "MIT",
6
6
  "repository": {
package/ui-core.js CHANGED
@@ -48,16 +48,57 @@ export function formatSeconds(s) {
48
48
  }
49
49
 
50
50
  /**
51
- * The rows a chart tooltip shows for one hovered datum, in the order the eye
52
- * reads the chart: a stack top segment first (series are given bottom-up, the
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 tooltipSeriesRows(datum, series, { stacked = false } = {}) {
57
- const rows = series
58
- .map(s => ({ key: s.key, label: s.label ?? s.key, color: s.color, value: datum?.[s.key] }))
59
- .filter(r => r.value != null && r.value !== 0 && !Number.isNaN(Number(r.value)));
60
- return stacked ? rows.reverse() : rows.sort((a, b) => Number(b.value) - Number(a.value));
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
- .mk-tip td { text-align: right; padding: 2px 0 0 12px; font-variant-numeric: tabular-nums; }
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
- * The hovered datum's series in reading order: stacked = top segment first
171
- * (pass series bottom-up, as drawn), else highest value first. Drops empty.
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?: { stacked?: boolean },
177
- ): { key: K; label: string; color?: string; value: number }[];
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, then a bold `total`
257
- * row under a rule. `after` rows follow the total, apart (a value on another
258
- * axis, such as an average next to a rate).
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(