@makoai/app-sdk 2.14.2 → 2.16.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
@@ -42,6 +42,36 @@ const { refresh, refreshing } = useQuery("latest_sales");
42
42
  </button>
43
43
  ```
44
44
 
45
+ ### Performance: SQL does the work
46
+
47
+ One 193k-row app froze ~10 s on every filter click. It loaded the binding
48
+ with `useQuery` and filtered it in a component. The rules:
49
+
50
+ 1. Filters, joins and aggregation run in SQL through `useDuckDB(sql)`, filters
51
+ in the `WHERE` clause. Only the rows a panel draws come back to JS.
52
+ `withConnection` serves a result several panels share. `useQuery(name)` is
53
+ for bindings under ~10k rows or already aggregated to what the page shows.
54
+ 2. One query per panel. Each panel returns a skeleton of its final size while
55
+ `loading`, never a "0" or an empty chart. Filter controls update on the
56
+ click frame; panels read filters through `useDeferredValue` or
57
+ `startTransition`.
58
+ 3. Measure before calling a UI done: the clicked control updates in under
59
+ 50 ms, no main-thread task runs over 200 ms during a filter change.
60
+ 4. Keep bindings small: aggregate in the binding, drop unused columns, split
61
+ a binding when one view needs far more rows.
62
+ 5. One engine: never a private parquet reader or a second DuckDB.
63
+
64
+ ```tsx
65
+ const f = useDeferredValue(country);
66
+ const q = useDuckDB(`select day, sum(revenue) r from latest_sales
67
+ where country = '${f.replace(/'/g, "''")}' group by 1 order by 1`);
68
+ if (q.loading) return <div className="skeleton" style={{ height: 280 }} />;
69
+ ```
70
+
71
+ In dev (`import.meta.env.DEV`), `useQuery` logs one `console.warn` per
72
+ binding that returns more than 20,000 rows, pointing to
73
+ `useDuckDB` (2.16+). Production builds never warn.
74
+
45
75
  ### Which SDK is running: `SDK_VERSION` (2.9+)
46
76
 
47
77
  `import { SDK_VERSION } from "@makoai/app-sdk"` is this package's version.
@@ -391,17 +421,26 @@ import {
391
421
  and declare it once (`src/vite-env.d.ts`):
392
422
  `declare const __APP_BINDING_NAMES__: string[];`
393
423
 
394
- ### Chart tooltips: `TableTooltip` (2.10+)
424
+ ### Chart tooltips: `TableTooltip` (2.10+, every series from 2.15)
395
425
 
396
426
  Every chart tooltip is a table, never recharts' coloured `name : value` list:
397
427
  a bold title, small muted column headers, one row per series with a 9px
398
428
  swatch in the series colour and the label in plain text, right-aligned
399
429
  tabular numbers, and a bold total row under a rule.
400
430
 
431
+ The tooltip lists every legend series, in legend order, in every bucket. Its
432
+ height and column widths never change while the pointer moves.
433
+
434
+ - A zero shows a muted "0", or a muted "0%" for a rate.
435
+ - A missing value shows a muted "–". Missing means the bucket has no data, or
436
+ the metric cannot be computed (a rate over a zero base).
437
+ - The value columns have a fixed minimum width (`--mk-tip-col`, default
438
+ `7ch`).
439
+
401
440
  ```tsx
402
- import { tableTooltip, tooltipSeriesRows } from "@makoai/app-sdk/ui";
441
+ import { tableTooltip, tooltipCell, tooltipSeriesRows } from "@makoai/app-sdk/ui";
403
442
 
404
- const SEGMENTS = [ // bottom-up, as stacked; drives the bars AND the tooltip
443
+ const SEGMENTS = [ // bottom-up, as stacked; drives the bars, the legend AND the tooltip
405
444
  { key: "new", label: "New", color: "var(--positive)" },
406
445
  { key: "churn", label: "Churn", color: "var(--negative)" },
407
446
  ];
@@ -411,16 +450,27 @@ const SEGMENTS = [ // bottom-up, as stacked; drives the bars AND the tooltip
411
450
  title: d.month,
412
451
  columns: ["MRR", "Orgs", "% of start"],
413
452
  rows: tooltipSeriesRows(d, SEGMENTS, { stacked: true }).map((r) => ({
414
- ...r, cells: [fmtEur(r.value), fmtInt(d[`orgs_${r.key}`]), fmtPct(r.value / d.start)],
453
+ ...r,
454
+ cells: [
455
+ tooltipCell(r.value, fmtEur),
456
+ tooltipCell(d[`orgs_${r.key}`], fmtInt),
457
+ tooltipCell(r.value == null || !d.start ? null : r.value / d.start, fmtPct, { percent: true }),
458
+ ],
415
459
  })),
416
460
  total: { label: "Net change", cells: [fmtEur(d.net), fmtInt(d.netOrgs), fmtPct(d.net / d.start)] },
417
461
  }))}
418
462
  />
419
463
  ```
420
464
 
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.
465
+ - `tooltipSeriesRows(datum, series, { stacked })` returns one row per series,
466
+ `{ key, label, color, value, state }`. A stack reads top segment first.
467
+ Other charts keep the series order, which is the legend order. `state` is
468
+ `"value"`, `"zero"` or `"missing"`. A missing `value` is `null`.
469
+ - `tooltipCell(value, format, { percent })` renders a cell: a muted "–" when
470
+ missing, a muted "0" or "0%" when zero, else `format(value)`.
471
+ `tooltipCellText` returns the same as `{ text, muted }` for non-React code.
472
+ - A `null` or `undefined` cell in `TableTooltip` shows a muted "–". An empty
473
+ string stays blank.
424
474
  - `total` is the stack total, "All selected", or the base the % is of.
425
475
  `after` rows follow it, apart: a value on another axis.
426
476
  - Precompute what the tooltip shows (totals, counts, bases) in each data row.
@@ -428,6 +478,13 @@ const SEGMENTS = [ // bottom-up, as stacked; drives the bars AND the tooltip
428
478
  - On a chart with an HTML overlay (a donut's centre label), lift the tooltip:
429
479
  `<Tooltip wrapperStyle={{ zIndex: 20 }} … />`.
430
480
 
481
+ **Opt-out.** Before 2.15, `tooltipSeriesRows` dropped zero and missing values
482
+ and sorted line charts highest value first. A caller that truly needs that
483
+ passes `{ hideEmpty: true, byValue: true }`. `hideEmpty` drops zero and
484
+ missing rows. `byValue` sorts non-stacked rows highest first, missing last.
485
+ Both make the tooltip change height or order between buckets, so the house
486
+ rule is to leave them off.
487
+
431
488
  ### Data tables: `DataTable` (2.11+)
432
489
 
433
490
  `DataTable` is the table the best workspace dashboards converged on: a card
package/data-core.js CHANGED
@@ -360,3 +360,22 @@ export function retryDelayMs(error, retries) {
360
360
  const wait = table[retries] ?? Infinity;
361
361
  return Math.max(wait, typeof error.retryAfterMs === "number" ? error.retryAfterMs : 0);
362
362
  }
363
+
364
+ /** Rows past which `useQuery` warns in dev: a page that filters this many in JS janks. */
365
+ export const LARGE_QUERY_ROWS = 20000;
366
+
367
+ /**
368
+ * The dev-console warning for a `useQuery` that handed JS `rows` rows, or null
369
+ * at or under `limit`. The fix is SQL: `useDuckDB` filters and aggregates in
370
+ * DuckDB and returns only what a panel draws.
371
+ */
372
+ export function largeQueryWarning(name, rows, limit = LARGE_QUERY_ROWS) {
373
+ if (!(rows > limit)) return null;
374
+ return (
375
+ "[@makoai/app-sdk] useQuery(" + JSON.stringify(String(name)) + ") returned " +
376
+ rows.toLocaleString("en-US") + " rows to JS. Filtering or aggregating them in a component " +
377
+ "blocks the main thread on every filter change. Run filters, joins and aggregation in SQL " +
378
+ "with useDuckDB(\"select … from " + quoteIdent(name) + " where …\"), one query per panel, " +
379
+ "so only the rows a panel draws come back. (Dev-only warning, shown once per binding.)"
380
+ );
381
+ }
package/index.js CHANGED
@@ -29,6 +29,7 @@ import {
29
29
  toPlainRows,
30
30
  parseBindingSnapshot,
31
31
  snapshotUrl,
32
+ largeQueryWarning,
32
33
  } from "./data-core.js";
33
34
 
34
35
  /**
@@ -36,7 +37,7 @@ import {
36
37
  * in a page (or this export) says which SDK a deployed app actually runs.
37
38
  * Kept in step with package.json by snapshot.test.mjs.
38
39
  */
39
- export const SDK_VERSION = "2.14.2";
40
+ export const SDK_VERSION = "2.16.0";
40
41
  if (typeof window !== "undefined") {
41
42
  try {
42
43
  window.__MAKO_APP_SDK__ = SDK_VERSION;
@@ -1680,6 +1681,18 @@ function useSnapshotPreview(name, enabled, rowLimit) {
1680
1681
  return preview;
1681
1682
  }
1682
1683
 
1684
+ // Vite replaces import.meta.env with { DEV: false, … } in every build, so this
1685
+ // is false in production and outside Vite (import.meta.env undefined).
1686
+ const DEV_BUILD = Boolean(import.meta.env && import.meta.env.DEV);
1687
+ const warnedLarge = new Set();
1688
+ function warnIfLarge(name, rows) {
1689
+ if (!DEV_BUILD || warnedLarge.has(name)) return;
1690
+ const message = largeQueryWarning(name, rows);
1691
+ if (!message) return;
1692
+ warnedLarge.add(name);
1693
+ console.warn(message);
1694
+ }
1695
+
1683
1696
  export function useQuery(name, opts) {
1684
1697
  bootEngine();
1685
1698
  const rowLimit = opts ? opts.rowLimit : undefined;
@@ -1690,6 +1703,7 @@ export function useQuery(name, opts) {
1690
1703
  hold(name);
1691
1704
  await registerBinding(name);
1692
1705
  const r = await runSql("SELECT * FROM " + quoteIdent(name), rowLimit, undefined, new Set([name]));
1706
+ warnIfLarge(name, r.rows.length);
1693
1707
  return { data: r.rows, fields: r.fields, truncated: r.truncated, rowCount: r.rowCount };
1694
1708
  },
1695
1709
  [name, rowLimit],
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@makoai/app-sdk",
3
- "version": "2.14.2",
3
+ "version": "2.16.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(