@makoai/app-sdk 2.9.0 → 2.10.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
@@ -262,6 +262,43 @@ import {
262
262
  and declare it once (`src/vite-env.d.ts`):
263
263
  `declare const __APP_BINDING_NAMES__: string[];`
264
264
 
265
+ ### Chart tooltips: `TableTooltip` (2.10+)
266
+
267
+ Every chart tooltip is a table, never recharts' coloured `name : value` list:
268
+ a bold title, small muted column headers, one row per series with a 9px
269
+ swatch in the series colour and the label in plain text, right-aligned
270
+ tabular numbers, and a bold total row under a rule.
271
+
272
+ ```tsx
273
+ import { tableTooltip, tooltipSeriesRows } from "@makoai/app-sdk/ui";
274
+
275
+ const SEGMENTS = [ // bottom-up, as stacked; drives the bars AND the tooltip
276
+ { key: "new", label: "New", color: "var(--positive)" },
277
+ { key: "churn", label: "Churn", color: "var(--negative)" },
278
+ ];
279
+
280
+ <Tooltip
281
+ content={tableTooltip((d) => ({
282
+ title: d.month,
283
+ columns: ["MRR", "Orgs", "% of start"],
284
+ rows: tooltipSeriesRows(d, SEGMENTS, { stacked: true }).map((r) => ({
285
+ ...r, cells: [fmtEur(r.value), fmtInt(d[`orgs_${r.key}`]), fmtPct(r.value / d.start)],
286
+ })),
287
+ total: { label: "Net change", cells: [fmtEur(d.net), fmtInt(d.netOrgs), fmtPct(d.net / d.start)] },
288
+ }))}
289
+ />
290
+ ```
291
+
292
+ - `tooltipSeriesRows(datum, series, { stacked })` puts the rows in reading
293
+ order (a stack's top segment first, lines highest first) and drops empty
294
+ values.
295
+ - `total` is the stack total, "All selected", or the base the % is of.
296
+ `after` rows follow it, apart: a value on another axis.
297
+ - Precompute what the tooltip shows (totals, counts, bases) in each data row.
298
+ The builder only reads and formats.
299
+ - On a chart with an HTML overlay (a donut's centre label), lift the tooltip:
300
+ `<Tooltip wrapperStyle={{ zIndex: 20 }} … />`.
301
+
265
302
  `ui.css` is plain CSS (no Tailwind needed; it coexists with Tailwind) and
266
303
  every kit class is prefixed `mk-`. It also sets the house base: Inter 14px on
267
304
  the warm `--canvas`.
package/index.d.ts CHANGED
@@ -365,3 +365,15 @@ export function useSearchParams(): [
365
365
  ) => void,
366
366
  ];
367
367
  export function navigate(to: string, opts?: { replace?: boolean }): void;
368
+ /**
369
+ * The Mako shortcut a keydown stands for ("mod+k" for Cmd/Ctrl+K), or null.
370
+ * Inside Mako the SDK forwards these to the host, because a cross-origin
371
+ * app frame keeps its keystrokes from Mako's own listeners.
372
+ */
373
+ export function hostShortcutFor(event: {
374
+ key: string;
375
+ metaKey: boolean;
376
+ ctrlKey: boolean;
377
+ altKey: boolean;
378
+ shiftKey: boolean;
379
+ }): "mod+k" | null;
package/index.js CHANGED
@@ -32,7 +32,7 @@ import {
32
32
  * in a page (or this export) says which SDK a deployed app actually runs.
33
33
  * Kept in step with package.json by snapshot.test.mjs.
34
34
  */
35
- export const SDK_VERSION = "2.9.0";
35
+ export const SDK_VERSION = "2.10.0";
36
36
  if (typeof window !== "undefined") {
37
37
  try {
38
38
  window.__MAKO_APP_SDK__ = SDK_VERSION;
@@ -790,6 +790,41 @@ export function navigate(to, opts) {
790
790
  }
791
791
  }
792
792
 
793
+ // ---------------------------------------------------------------------------
794
+ // Host shortcuts — keys that belong to Mako, not the app.
795
+ //
796
+ // On its own origin (<appId>.makousercontent.com) the app is a cross-origin
797
+ // frame: a keydown while it has focus reaches only this document, so Mako's
798
+ // Cmd/Ctrl+K never fired. Hand the shortcut to the host instead, the same
799
+ // way navigate() hands over the query. Capture phase, so an app's own
800
+ // handlers cannot swallow it first.
801
+ // ---------------------------------------------------------------------------
802
+ export function hostShortcutFor(event) {
803
+ if (!(event.metaKey || event.ctrlKey) || event.altKey || event.shiftKey) {
804
+ return null;
805
+ }
806
+ return typeof event.key === "string" && event.key.toLowerCase() === "k"
807
+ ? "mod+k"
808
+ : null;
809
+ }
810
+
811
+ if (typeof window !== "undefined" && window.parent !== window) {
812
+ window.addEventListener(
813
+ "keydown",
814
+ event => {
815
+ const key = hostShortcutFor(event);
816
+ if (!key) return;
817
+ event.preventDefault();
818
+ try {
819
+ window.parent.postMessage({ type: "mako-app:shortcut", key }, "*");
820
+ } catch {
821
+ // A host that is not Mako: nothing to tell.
822
+ }
823
+ },
824
+ true,
825
+ );
826
+ }
827
+
793
828
  export function useLocation() {
794
829
  const [loc, setLoc] = React.useState(readLocation);
795
830
  React.useEffect(() => {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@makoai/app-sdk",
3
- "version": "2.9.0",
3
+ "version": "2.10.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
@@ -46,3 +46,16 @@ export function refreshOrder(bindings, { first = [], last = [], skip = [] } = {}
46
46
  export function formatSeconds(s) {
47
47
  return s >= 60 ? `${Math.floor(s / 60)}m ${String(s % 60).padStart(2, "0")}s` : `${s}s`;
48
48
  }
49
+
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 }`.
55
+ */
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));
61
+ }
package/ui.css CHANGED
@@ -122,6 +122,21 @@ button:not(:disabled), [role="button"]:not(:disabled) { cursor: pointer; }
122
122
  }
123
123
  }
124
124
 
125
+ /* ---- Chart tooltip (TableTooltip) ---------------------------------------- */
126
+ .mk-tip {
127
+ background: var(--popover); color: var(--popover-foreground);
128
+ border: 1px solid var(--border); border-radius: 8px; box-shadow: var(--mk-shadow-md);
129
+ padding: 8px 10px; font-size: 12px; line-height: 1.4; white-space: nowrap;
130
+ }
131
+ .mk-tip-title { font-weight: 600; margin-bottom: 4px; }
132
+ .mk-tip table { border-collapse: collapse; }
133
+ .mk-tip thead th { color: var(--muted-foreground); font-weight: 500; text-align: right; padding-left: 12px; }
134
+ .mk-tip tbody th { text-align: left; font-weight: 400; padding-top: 2px; }
135
+ .mk-tip td { text-align: right; padding: 2px 0 0 12px; font-variant-numeric: tabular-nums; }
136
+ .mk-tip-swatch { display: inline-block; width: 9px; height: 9px; border-radius: 2px; margin-right: 6px; }
137
+ .mk-tip-total th, .mk-tip-total td { font-weight: 600; }
138
+ .mk-tip-rule th, .mk-tip-rule td { border-top: 1px solid var(--border); padding-top: 3px; }
139
+
125
140
  /* ---- MultiSelect --------------------------------------------------------- */
126
141
  .mk-ms { position: relative; display: inline-block; }
127
142
  .mk-ms-trigger {
package/ui.d.ts CHANGED
@@ -139,3 +139,39 @@ export interface RefreshAllButtonProps {
139
139
  className?: string;
140
140
  }
141
141
  export function RefreshAllButton(props: RefreshAllButtonProps): React.ReactElement;
142
+
143
+ /** One tooltip row: swatch + label, then the cells (right-aligned). */
144
+ export interface TooltipRow {
145
+ label: React.ReactNode;
146
+ /** The series colour for the 9px swatch; omit for no swatch. */
147
+ color?: string;
148
+ cells: React.ReactNode[];
149
+ key?: string;
150
+ }
151
+ export interface TableTooltipProps {
152
+ title?: React.ReactNode;
153
+ /** Column headers for the cells, e.g. ["MRR", "Orgs", "% of due"]. */
154
+ columns?: string[];
155
+ /** Top-down as drawn (see `tooltipSeriesRows`). */
156
+ rows?: TooltipRow[];
157
+ /** Bold row under a rule: the stack total, "All selected", the base. */
158
+ total?: TooltipRow;
159
+ /** Rows after the total, apart: a value on another axis. */
160
+ after?: TooltipRow[];
161
+ className?: string;
162
+ }
163
+ /** The house chart tooltip: a table with swatches, right-aligned numbers and a total row. */
164
+ export function TableTooltip(props: TableTooltipProps): React.ReactElement;
165
+ /** A recharts `<Tooltip content={tableTooltip((datum, label) => ({ … }))} />`. */
166
+ export function tableTooltip<D = any>(
167
+ build: (datum: D, label: unknown) => TableTooltipProps | null,
168
+ ): (props: { active?: boolean; payload?: readonly { payload?: unknown }[]; label?: unknown }) => React.ReactElement | null;
169
+ /**
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.
172
+ */
173
+ export function tooltipSeriesRows<K extends string>(
174
+ datum: Record<string, unknown> | null | undefined,
175
+ series: readonly { key: K; label?: string; color?: string }[],
176
+ opts?: { stacked?: boolean },
177
+ ): { key: K; label: string; color?: string; value: number }[];
package/ui.js CHANGED
@@ -11,9 +11,9 @@
11
11
  import * as React from "react";
12
12
  import { createPortal } from "react-dom";
13
13
  import { bindingPhaseLabel, refreshBinding, useBindingProgress } from "./index.js";
14
- import { formatSeconds as fmtSecs, normalizeTone, refreshOrder } from "./ui-core.js";
14
+ import { formatSeconds as fmtSecs, normalizeTone, refreshOrder, tooltipSeriesRows } from "./ui-core.js";
15
15
 
16
- export { normalizeTone, refreshOrder };
16
+ export { normalizeTone, refreshOrder, tooltipSeriesRows };
17
17
 
18
18
  const h = React.createElement;
19
19
 
@@ -197,6 +197,68 @@ export function KpiRow({ className, children }) {
197
197
  return h("div", { className: cx("mk-kpi-row", className) }, children);
198
198
  }
199
199
 
200
+ // ---------------------------------------------------------------------------
201
+ // Chart tooltips: a table, never a coloured "name : value" list
202
+ // ---------------------------------------------------------------------------
203
+
204
+ function TooltipRow({ row, className }) {
205
+ return h(
206
+ "tr",
207
+ { className },
208
+ h(
209
+ "th",
210
+ { scope: "row" },
211
+ h("span", { className: "mk-tip-swatch", style: { background: row.color ?? "transparent" } }),
212
+ row.label,
213
+ ),
214
+ ...(row.cells ?? []).map((c, i) => h("td", { key: i }, c)),
215
+ );
216
+ }
217
+
218
+ /**
219
+ * The house chart tooltip: a bold title, small muted column headers, one row
220
+ * per series with a 9px swatch in the series colour and the label in the
221
+ * popover's text colour, right-aligned tabular numbers, then a bold `total`
222
+ * row under a rule. `after` rows follow the total, apart (a value on another
223
+ * axis, such as an average next to a rate).
224
+ */
225
+ export function TableTooltip({ title, columns = [], rows = [], total, after, className }) {
226
+ return h(
227
+ "div",
228
+ { className: cx("mk-tip", className) },
229
+ title != null && h("div", { className: "mk-tip-title" }, title),
230
+ h(
231
+ "table",
232
+ null,
233
+ columns.length > 0 &&
234
+ h("thead", null, h("tr", null, h("th", null), ...columns.map(c => h("th", { key: c }, c)))),
235
+ h(
236
+ "tbody",
237
+ null,
238
+ ...rows.map(r => h(TooltipRow, { key: r.key ?? r.label, row: r })),
239
+ total && h(TooltipRow, { key: "__total", row: total, className: cx("mk-tip-total", rows.length > 0 && "mk-tip-rule") }),
240
+ ...(after ?? []).map((r, i) =>
241
+ h(TooltipRow, { key: `__after_${r.key ?? r.label}`, row: r, className: i === 0 ? "mk-tip-rule" : undefined }),
242
+ ),
243
+ ),
244
+ ),
245
+ );
246
+ }
247
+
248
+ /**
249
+ * A recharts `<Tooltip content={…} />` from a builder: `build(datum, label)`
250
+ * gets the hovered data row and the axis label and returns TableTooltip props
251
+ * (or null to show nothing).
252
+ */
253
+ export function tableTooltip(build) {
254
+ return function TableTooltipContent({ active, payload, label }) {
255
+ const datum = payload?.[0]?.payload;
256
+ if (!active || !datum) return null;
257
+ const props = build(datum, label);
258
+ return props ? h(TableTooltip, props) : null;
259
+ };
260
+ }
261
+
200
262
  // ---------------------------------------------------------------------------
201
263
  // MultiSelect
202
264
  // ---------------------------------------------------------------------------