fix: sound metric-view row/time typing, currency + cache correctness, review cleanup

Address adversarial-review findings on the useMetricView / metric-route branch:

- Type soundness: infer rows from the selected measure/dimension tuples
  (PickMetricRow) and correlate timeDimension/timeGrain to temporal dims only.
- Formatting: preserve every currency symbol the generator emits end-to-end and
  keep bigint precision (no Number() rounding).
- Cache correctness: stamp fresh per-column metadata AFTER the cached execute()
  so a cache hit never serves stale labels/formats after a redeploy.
- Charts: guard selected="" as a no-op, split [x,y] click tuples into x/y, and
  memoize onEvents on handler presence (no listener thrash per SSE tick).
- Typegen: sweep a stale sibling metric-views.d.ts on upgrade and reject a
  .d.ts mvOutFile.
- Drop the unused public notify export and the fake "Write back" demo; remove
  the dead autoStart option; align AnalyticsStreamMessage; tighten the biome
  ignore; add tests + comment cleanup.

Co-authored-by: Isaac
Signed-off-by: Atila Fassina <atila@fassina.eu>

Author: atilafassina

apps/dev-playground/client/src/routes/metric-views.route.tsx

@@ -16,7 +16,6 @@ import {
   CardTitle,
   DonutChart,
   LineChart,
-  notify,
   Select,
   SelectContent,
   SelectItem,
@@ -54,10 +53,10 @@ const TREND_MEASURES = ["arr", "mrr"] as const;
 const TABLE_MEASURES = ["arr", "mrr", "new_arr", "churned_arr"] as const;
 const TABLE_COLUMNS = ["region", ...TABLE_MEASURES] as const;
 
-// The dimensions the page lets you slice by. Both the filter bar (dropdowns)
-// and the detail table (row click) write selections keyed by these names, and
-// every visual composes them into a `MetricFilter` the same way — so a future
-// chart-click cross-filter drops into the same `selection` state unchanged.
+// The dimensions the page lets you slice by. The filter-bar dropdowns, the
+// detail-table row click, AND the chart clicks (region bar / segment donut)
+// all write selections keyed by these names, and every visual composes them
+// into a `MetricFilter` the same way — one shared `selection` state drives them.
 const FILTER_DIMENSIONS = ["region", "segment"] as const;
 type FilterDimension = (typeof FILTER_DIMENSIONS)[number];
 type Selection = Partial<Record<FilterDimension, string>>;
@@ -450,45 +449,6 @@ function MetricViewsRoute() {
                   yKey={[...TREND_MEASURES]}
                   height={320}
                   showLegend
-                  // Render point symbols + trigger clicks along the whole line
-                  // (SDK's triggerLineEvent, on because onDataClick is set) so
-                  // the hairline isn't the only hit target.
-                  showSymbol
-                  // Clicking a point fires a transient "write-back" toast (the
-                  // "Apps = action layer" gesture) through the same Toaster the
-                  // warehouse-status indicator uses.
-                  onDataClick={(d) => {
-                    // Resolve the measure by series INDEX — yKey order ===
-                    // TREND_MEASURES order, and sorting only reorders points
-                    // WITHIN a series, not the series array. (Parsing the "Arr"
-                    // label wouldn't round-trip to keys like "new_arr", and
-                    // indexing trend.data by dataIndex is wrong because the
-                    // time series is sorted before rendering.)
-                    const measureKey = TREND_MEASURES[d.seriesIndex];
-                    if (!measureKey) return;
-                    const meta = trend.metadata?.[measureKey];
-                    const label = meta?.display_name ?? measureKey;
-                    // A time-series point is a [epochMs, value] tuple on
-                    // ECharts' params.value (d.value is null for tuples); read
-                    // it off the raw params so both the date and amount survive.
-                    const tuple = (d.raw as { value?: unknown } | undefined)
-                      ?.value;
-                    const [ts, amount] = Array.isArray(tuple)
-                      ? tuple
-                      : [undefined, undefined];
-                    const month =
-                      typeof ts === "number"
-                        ? new Date(ts).toLocaleDateString(undefined, {
-                            year: "numeric",
-                            month: "short",
-                          })
-                        : String(d.name || "");
-                    const formatted = formatValue(amount, meta?.format);
-                    notify.message(
-                      `Write back: ${label} · ${month} · ${formatted}`,
-                      { description: "Point selected for write-back (demo)." },
-                    );
-                  }}
                 />
               )}
           </CardContent>

biome.json

@@ -21,8 +21,8 @@
       "!**/*.gen.ts",
       "!**/typedoc-sidebar.ts",
       "!**/template",
-      "!**/metric-views.ts",
-      "!**/metric-views.d.ts"
+      "!**/appkit-types/metric-views.ts",
+      "!**/appkit-types/metric-views.d.ts"
     ]
   },
   "formatter": {

docs/docs/plugins/analytics.md

@@ -535,7 +535,7 @@ When `"revenue"` is a key in the generated `MetricRegistry` (see [Metric-view ty
 }
 ```
 
-Like `useAnalyticsQuery`, the option object is serialized internally, so object/array literals passed fresh each render stay referentially stable — you do **not** need to `useMemo` the options. (Hoisting `measures`/`dimensions` to module scope or memoizing is still fine, and keeps the arrays type-narrowed to their literal tuple.)
+Like `useAnalyticsQuery`, the option object is serialized (`JSON.stringify`) internally, so object/array literals passed fresh each render do **not** trigger a refetch as long as they serialize to the same string — you do **not** need to `useMemo` the options. (This is same-serialization, not deep structural equality: reordering keys within `filter` changes the string and does re-query. Hoisting `measures`/`dimensions` to module scope or memoizing is still fine, and keeps the arrays type-narrowed to their literal tuple.)
 
 `metadata` is the per-column display metadata for **only the columns you queried**, scoped and carried in the SSE `result` payload. It is `undefined` when the server injected no metadata (the metric key is unknown, or `analytics({ metricViewsMetadata })` was not wired) — so always treat it as optional.
 

packages/appkit-ui/src/js/format/format.test.ts

@@ -34,6 +34,20 @@ describe("js/format formatValue", () => {
     expect(formatValue(1234567n, "#,##0")).toBe("1,234,567");
   });
 
+  test("preserves bigint precision beyond 2^53 (no Number() rounding)", () => {
+    // 9_007_199_254_740_993n = 2^53 + 1, which is NOT representable as a JS
+    // number — Number(bigint) would round it to 9_007_199_254_740_992.
+    expect(formatValue(9_007_199_254_740_993n, "#,##0")).toBe(
+      "9,007,199,254,740,993",
+    );
+    expect(formatValue(9_007_199_254_740_993n, "$#,##0")).toBe(
+      "$9,007,199,254,740,993",
+    );
+    expect(formatValue(-9_007_199_254_740_993n, "$#,##0")).toBe(
+      "-$9,007,199,254,740,993",
+    );
+  });
+
   test("no format falls back to toLocaleString for numbers", () => {
     expect(formatValue(1234.5)).toBe((1234.5).toLocaleString());
   });
@@ -51,6 +65,28 @@ describe("js/format formatValue", () => {
   test("non-numeric value with numeric spec falls back to String()", () => {
     expect(formatValue("N/A", "#,##0")).toBe("N/A");
   });
+
+  // End-to-end over the currency symbols the metric-view generator emits
+  // (mv-registry/describe.ts CURRENCY_SYMBOLS + the unknown-code fallback).
+  // Each spec here is exactly what the generator produces for that symbol.
+  describe("preserves every currency symbol the generator emits", () => {
+    test.each([
+      ["$#,##0.00", 1234.5, "$1,234.50"], // USD
+      ["€#,##0.00", 1234.5, "€1,234.50"], // EUR
+      ["£#,##0.00", 1234.5, "£1,234.50"], // GBP
+      ["¥#,##0", 1234, "¥1,234"], // JPY / CNY
+      ["₹#,##0.00", 1234.5, "₹1,234.50"], // INR
+      ["R$#,##0.00", 1234.5, "R$1,234.50"], // BRL (multi-char symbol)
+      ["XYZ #,##0.00", 1234.5, "XYZ 1,234.50"], // unknown ISO code + space
+    ])("formatValue(%s) preserves the symbol", (spec, value, expected) => {
+      expect(formatValue(value, spec)).toBe(expected);
+    });
+
+    test("negative currency keeps the sign before the symbol for every prefix", () => {
+      expect(formatValue(-1234.5, "€#,##0.00")).toBe("-€1,234.50");
+      expect(formatValue(-1234.5, "R$#,##0.00")).toBe("-R$1,234.50");
+    });
+  });
 });
 
 describe("js/format formatLabel", () => {
@@ -93,4 +129,19 @@ describe("js/format toD3Format", () => {
     expect(toD3Format("yyyy-MM-dd")).toBeUndefined();
     expect(toD3Format("abc")).toBeUndefined();
   });
+
+  // Every currency spec the generator emits maps to d3's `$` currency type
+  // (the actual glyph is supplied by the consuming d3 locale, not the
+  // specifier) — none of them are dropped as unrecognized.
+  test.each([
+    ["$#,##0.00", "$,.2f"],
+    ["€#,##0.00", "$,.2f"],
+    ["£#,##0.00", "$,.2f"],
+    ["¥#,##0", "$,.0f"],
+    ["₹#,##0.00", "$,.2f"],
+    ["R$#,##0.00", "$,.2f"],
+    ["XYZ #,##0.00", "$,.2f"],
+  ])("maps currency spec %s to a $-typed d3 specifier", (spec, expected) => {
+    expect(toD3Format(spec)).toBe(expected);
+  });
 });

packages/appkit-ui/src/js/format/format.ts

@@ -49,11 +49,24 @@ function formatNumber(
   });
 }
 
+/**
+ * The currency symbol a spec carries — everything before the first digit
+ * placeholder (`#`/`0`). The metric-view generator emits `$`, `€`, `£`, `¥`,
+ * `₹`, `R$`, or an unknown ISO code + space (e.g. `"XYZ "`); this recovers any
+ * of them verbatim. Returns `""` for a bare numeric spec (`"#,##0"`) or a
+ * percent spec (`"0.0%"`), neither of which has a leading symbol.
+ */
+function currencyPrefix(format: string): string {
+  const match = format.match(/^[^#0]+/);
+  return match ? match[0] : "";
+}
+
 /**
  * Format a raw value using a UC/YAML printf-style format spec.
  *
  * Recognizes the common spreadsheet-style specs:
- * - currency prefix, e.g. `"$#,##0.00"` (1234.5 -> "$1,234.50")
+ * - currency prefix, e.g. `"$#,##0.00"` (1234.5 -> "$1,234.50"); the prefix is
+ *   emitted verbatim, so `"€#,##0"`, `"R$#,##0.00"`, etc. survive end-to-end
  * - thousands grouping + N decimals, e.g. `"#,##0"` (1234567 -> "1,234,567")
  *   or `"#,##0.00"` (1234.5 -> "1,234.50")
  * - percent, e.g. `"0.0%"` (0.1234 -> "12.3%") — the value is multiplied by 100
@@ -73,22 +86,42 @@ export function formatValue(value: unknown, format?: string): string {
     return String(value);
   }
 
-  const num = coerceNumber(value);
-  // Non-numeric value with a numeric-ish spec: nothing sensible to format.
-  if (num === null) return String(value);
-
   const isPercent = format.includes("%");
-  const isCurrency = format.includes("$");
   const grouping = format.includes(",");
   const decimals = countDecimals(format);
+  // Any leading symbol (before the first digit placeholder) is a currency
+  // prefix — emit it verbatim so non-USD symbols the generator produces are
+  // preserved instead of collapsing to "$".
+  const prefix = currencyPrefix(format);
+
+  // bigint fast path. A bigint is an exact integer, so `BigInt.toLocaleString`
+  // formats it losslessly — `Number(bigint)` would corrupt values beyond ±2^53
+  // (int64 counts / cents). The percent path multiplies by 100 (float math a
+  // large bigint can't survive), so refuse it rather than emit a wrong number.
+  if (typeof value === "bigint") {
+    if (isPercent) return String(value);
+    const sign = value < 0n ? "-" : "";
+    // `Intl.NumberFormat` accepts a bigint directly and formats it exactly (no
+    // float coercion), unlike `Number(value)`.
+    const body = new Intl.NumberFormat("en-US", {
+      minimumFractionDigits: decimals,
+      maximumFractionDigits: decimals,
+      useGrouping: grouping,
+    }).format(value < 0n ? -value : value);
+    return `${sign}${prefix}${body}`;
+  }
+
+  const num = coerceNumber(value);
+  // Non-numeric value with a numeric-ish spec: nothing sensible to format.
+  if (num === null) return String(value);
 
   if (isPercent) {
     return `${formatNumber(num * 100, decimals, grouping)}%`;
   }
 
-  if (isCurrency) {
+  if (prefix) {
     const sign = num < 0 ? "-" : "";
-    return `${sign}$${formatNumber(Math.abs(num), decimals, grouping)}`;
+    return `${sign}${prefix}${formatNumber(Math.abs(num), decimals, grouping)}`;
   }
 
   return formatNumber(num, decimals, grouping);
@@ -136,19 +169,25 @@ export function formatLabel(
  *
  * Best-effort mapping for the common specs:
  * - `"$#,##0.00"` -> `"$,.2f"`
- * - `"#,##0"`     -> `",.0f"`
- * - `"#,##0.00"`  -> `",.2f"`
- * - `"0.0%"`      -> `".1%"`
+ * - `"€#,##0.00"` -> `"$,.2f"` (currency), `"#,##0"` -> `",.0f"`, `"0.0%"` -> `".1%"`
+ *
+ * A d3 specifier's currency marker is the single `$` symbol; the actual glyph
+ * ($, €, R$, …) is supplied by the d3 *locale*, not the specifier string — so a
+ * non-USD currency spec still maps to the `$` currency type here (it is not
+ * rejected as unrecognized), and the caller's d3 locale renders the right glyph.
  *
  * No spec, or a spec that is not a recognizable numeric pattern -> `undefined`.
  */
 export function toD3Format(format?: string): string | undefined {
   if (!format) return undefined;
 
-  // Only map specs built purely from numeric-format characters; anything else
-  // (date patterns, free text, ...) is left unrecognized.
-  if (format.replace(/[#0,.$%\s]/g, "") !== "") return undefined;
-  if (!/[0#]/.test(format)) return undefined;
+  // Strip any leading currency prefix first, then require the remainder to be
+  // built purely from numeric-format characters; anything else (date patterns,
+  // free text, ...) is left unrecognized.
+  const prefix = currencyPrefix(format);
+  const numeric = format.slice(prefix.length);
+  if (numeric.replace(/[#0,.%\s]/g, "") !== "") return undefined;
+  if (!/[0#]/.test(numeric)) return undefined;
 
   const group = format.includes(",") ? "," : "";
   const decimals = countDecimals(format);
@@ -157,6 +196,7 @@ export function toD3Format(format?: string): string | undefined {
     return `${group}.${decimals}%`;
   }
 
-  const prefix = format.includes("$") ? "$" : "";
-  return `${prefix}${group}.${decimals}f`;
+  // `$` is d3's currency marker (glyph comes from the locale); emit it for any
+  // currency prefix, USD or otherwise.
+  return `${prefix ? "$" : ""}${group}.${decimals}f`;
 }