feat(appkit): metric-view hook, formatters, generator const + payload metadata (PR5 1-4)

Implement the four parallel PR5 slices against the frozen phase-0 contracts:

- Generator (type-generator): emit metric-views.ts (was .d.ts) carrying both
  the erasable declare-module MetricRegistry augmentation and a runtime
  `export const metricViewsMetadata = {...} as const`. Header is a type-only
  import (no runtime side-effect import on the Node server). Rename propagated
  through METRIC_TYPES_FILE, mvOutFile, vite-plugin, CLI announce, and tests;
  generated .ts added to Biome ignore.
- Server (analytics plugin): accept an injected `metricViewsMetadata` config
  and stamp the responding metric's per-column slice (scoped to the requested
  measures/dimensions) into the SSE result payload. Metadata is response
  decoration — it never enters composeMetricCacheKey and never alters SQL.
- Hook (appkit-ui): `useMetricView(key, opts)` mirroring useAnalyticsQuery
  (SSE, abort-on-arg-change, autoStart), returning
  { data, loading, error, errorCode, metadata }.
- Formatters (appkit-ui js): pure, React-free, tree-shakeable formatValue /
  formatLabel / toD3Format taking the format spec / column metadata as args.

Also fix a pre-existing latent port collision: analytics.integration.test.ts
and server.integration.test.ts both hardcoded port 9879; under the added
metric-test weight they could bind concurrently in the shared vitest worker
pool, so an analytics request hit the server-plugin app and 404'd. Switch the
analytics integration test to an OS-assigned ephemeral port (port: 0), matching
the files plugin integration test.

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

Author: atilafassina

biome.json

@@ -20,7 +20,9 @@
       "!**/*.gen.css",
       "!**/*.gen.ts",
       "!**/typedoc-sidebar.ts",
-      "!**/template"
+      "!**/template",
+      "!**/metric-views.ts",
+      "!**/metric-views.d.ts"
     ]
   },
   "formatter": {

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

@@ -0,0 +1,96 @@
+import { describe, expect, test } from "vitest";
+import { formatLabel, formatValue, toD3Format } from "./format";
+
+describe("js/format formatValue", () => {
+  test("currency spec formats with prefix, grouping and 2 decimals", () => {
+    expect(formatValue(1234.5, "$#,##0.00")).toBe("$1,234.50");
+  });
+
+  test("currency spec handles negatives with sign before the symbol", () => {
+    expect(formatValue(-1234.5, "$#,##0.00")).toBe("-$1,234.50");
+  });
+
+  test("integer spec groups thousands with no decimals", () => {
+    expect(formatValue(1234567, "#,##0")).toBe("1,234,567");
+  });
+
+  test("decimal grouping spec keeps N decimals", () => {
+    expect(formatValue(1234.5, "#,##0.00")).toBe("1,234.50");
+  });
+
+  test("percent spec multiplies by 100 and appends %", () => {
+    expect(formatValue(0.1234, "0.0%")).toBe("12.3%");
+  });
+
+  test("integer percent spec has no decimals", () => {
+    expect(formatValue(0.5, "0%")).toBe("50%");
+  });
+
+  test("accepts numeric strings", () => {
+    expect(formatValue("1234.5", "$#,##0.00")).toBe("$1,234.50");
+  });
+
+  test("accepts bigint values", () => {
+    expect(formatValue(1234567n, "#,##0")).toBe("1,234,567");
+  });
+
+  test("no format falls back to toLocaleString for numbers", () => {
+    expect(formatValue(1234.5)).toBe((1234.5).toLocaleString());
+  });
+
+  test("no format passes through strings", () => {
+    expect(formatValue("hello")).toBe("hello");
+  });
+
+  test("null and undefined become empty string", () => {
+    expect(formatValue(null)).toBe("");
+    expect(formatValue(undefined)).toBe("");
+    expect(formatValue(null, "$#,##0.00")).toBe("");
+  });
+
+  test("non-numeric value with numeric spec falls back to String()", () => {
+    expect(formatValue("N/A", "#,##0")).toBe("N/A");
+  });
+});
+
+describe("js/format formatLabel", () => {
+  test("display_name wins over the raw name", () => {
+    const meta = { type: "double", display_name: "Avg LTV" };
+    expect(formatLabel("avg_ltv", meta)).toBe("Avg LTV");
+  });
+
+  test("humanizes snake_case when no display_name", () => {
+    expect(formatLabel("avg_ltv")).toBe("Avg Ltv");
+  });
+
+  test("humanizes camelCase", () => {
+    expect(formatLabel("totalSpend")).toBe("Total Spend");
+  });
+
+  test("humanizes ALL_CAPS", () => {
+    expect(formatLabel("TOTAL_SPEND")).toBe("Total Spend");
+  });
+
+  test("columnMeta without display_name falls back to humanize", () => {
+    expect(formatLabel("user_name", { type: "string" })).toBe("User Name");
+  });
+});
+
+describe("js/format toD3Format", () => {
+  test("maps the common numeric specs", () => {
+    expect(toD3Format("$#,##0.00")).toBe("$,.2f");
+    expect(toD3Format("#,##0")).toBe(",.0f");
+    expect(toD3Format("#,##0.00")).toBe(",.2f");
+    expect(toD3Format("0.0%")).toBe(".1%");
+  });
+
+  test("no spec returns undefined", () => {
+    expect(toD3Format()).toBeUndefined();
+    expect(toD3Format("")).toBeUndefined();
+  });
+
+  test("unrecognized specs return undefined", () => {
+    expect(toD3Format("yyyy-MM-dd")).toBeUndefined();
+    expect(toD3Format("abc")).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,162 @@
+import type { MetricColumnMeta } from "shared";
+
+// ============================================================================
+// Pure Format Utilities
+// ============================================================================
+// Library-agnostic, tree-shakeable helpers for turning raw metric values and
+// column metadata into display strings. These take the UC/YAML format spec (or
+// MetricColumnMeta) as ARGUMENTS — no React, no chart-lib coupling, no bundled
+// artifact — so they can be used from any surface (tables, tooltips, charts).
+
+/**
+ * Counts the number of fractional digits declared by a numeric format spec.
+ * E.g. "#,##0.00" -> 2, "#,##0" -> 0, "0.0%" -> 1.
+ */
+function countDecimals(format: string): number {
+  const dotIndex = format.indexOf(".");
+  if (dotIndex === -1) return 0;
+  const frac = format.slice(dotIndex + 1);
+  const match = frac.match(/^[0#]+/);
+  return match ? match[0].length : 0;
+}
+
+/**
+ * Best-effort coercion of an arbitrary value to a finite number. Handles the
+ * common wire shapes (number, bigint, numeric string). Returns null when the
+ * value cannot be meaningfully treated as a number.
+ */
+function coerceNumber(value: unknown): number | null {
+  if (typeof value === "number") return Number.isFinite(value) ? value : null;
+  if (typeof value === "bigint") return Number(value);
+  if (typeof value === "string") {
+    if (value.trim() === "") return null;
+    const n = Number(value);
+    return Number.isFinite(n) ? n : null;
+  }
+  return null;
+}
+
+/** Format a number with fixed decimals + optional thousands grouping. */
+function formatNumber(
+  value: number,
+  decimals: number,
+  grouping: boolean,
+): string {
+  return value.toLocaleString("en-US", {
+    minimumFractionDigits: decimals,
+    maximumFractionDigits: decimals,
+    useGrouping: grouping,
+  });
+}
+
+/**
+ * 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")
+ * - 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
+ *
+ * No format spec -> sensible default: numbers via `toLocaleString`, everything
+ * else via `String()`. `null`/`undefined` -> `""`. Unrecognized specs fall back
+ * to a best-effort result (the number grouped, or `String(value)`).
+ */
+export function formatValue(value: unknown, format?: string): string {
+  if (value === null || value === undefined) return "";
+
+  if (!format) {
+    if (typeof value === "number") {
+      return Number.isFinite(value) ? value.toLocaleString() : String(value);
+    }
+    if (typeof value === "bigint") return value.toLocaleString();
+    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);
+
+  if (isPercent) {
+    return `${formatNumber(num * 100, decimals, grouping)}%`;
+  }
+
+  if (isCurrency) {
+    const sign = num < 0 ? "-" : "";
+    return `${sign}$${formatNumber(Math.abs(num), decimals, grouping)}`;
+  }
+
+  return formatNumber(num, decimals, grouping);
+}
+
+/**
+ * Turns a raw column name into a human-readable label.
+ * Handles camelCase, snake_case, acronyms, and ALL_CAPS.
+ * E.g., "totalSpend" -> "Total Spend", "avg_ltv" -> "Avg Ltv".
+ */
+function humanize(name: string): string {
+  return (
+    name
+      // Handle consecutive uppercase followed by lowercase (e.g., HTTPUrl -> HTTP Url)
+      .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+      // Handle lowercase followed by uppercase (e.g., totalSpend -> total Spend)
+      .replace(/([a-z])([A-Z])/g, "$1 $2")
+      // Replace underscores with spaces
+      .replace(/_/g, " ")
+      // Collapse multiple spaces into one
+      .replace(/\s+/g, " ")
+      // Normalize to title case
+      .toLowerCase()
+      .replace(/\b\w/g, (l) => l.toUpperCase())
+      .trim()
+  );
+}
+
+/**
+ * Human label for a column: prefers `columnMeta.display_name`, else humanizes
+ * the raw column name (camelCase / snake_case / CAPS -> Title Case).
+ */
+export function formatLabel(
+  name: string,
+  columnMeta?: MetricColumnMeta,
+): string {
+  if (columnMeta?.display_name) return columnMeta.display_name;
+  return humanize(name);
+}
+
+/**
+ * Maps a UC/spreadsheet-style format spec to a
+ * [d3-format](https://d3js.org/d3-format) specifier string, for charts that
+ * consume d3 format strings.
+ *
+ * Best-effort mapping for the common specs:
+ * - `"$#,##0.00"` -> `"$,.2f"`
+ * - `"#,##0"`     -> `",.0f"`
+ * - `"#,##0.00"`  -> `",.2f"`
+ * - `"0.0%"`      -> `".1%"`
+ *
+ * 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;
+
+  const group = format.includes(",") ? "," : "";
+  const decimals = countDecimals(format);
+
+  if (format.includes("%")) {
+    return `${group}.${decimals}%`;
+  }
+
+  const prefix = format.includes("$") ? "$" : "";
+  return `${prefix}${group}.${decimals}f`;
+}

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

@@ -0,0 +1 @@
+export * from "./format";

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

@@ -12,4 +12,5 @@ export {
 export * from "./arrow";
 export * from "./config";
 export * from "./constants";
+export * from "./format";
 export * from "./sse";