feat: metric-view runtime

apps/dev-playground/config/queries/metric-views.json → apps/dev-playground/config/metric-views/definitions.json

@@ -1,4 +1,5 @@
 {
+  "$schema": "https://databricks.github.io/appkit/schemas/metric-source.schema.json",
   "metricViews": {
     "revenue": {
       "source": "appkit_demo.public.revenue_metrics"

apps/dev-playground/shared/appkit-types/metric-views.d.ts

@@ -30,23 +30,31 @@ declare module "@databricks/appkit-ui/react" {
         measures: {
       "active_accounts": {
         type: "bigint";
+        display_name: "Active Accounts";
+        format: "#,##0";
       };
       "churn_rate": {
         type: "decimal";
+        display_name: "Churn Rate";
       };
       "avg_ltv": {
         type: "double";
+        display_name: "Average LTV";
+        format: "$#,##0.00";
       };
     };
         dimensions: {
       "segment": {
         type: "string";
+        display_name: "Customer Segment";
       };
       "region": {
         type: "string";
+        display_name: "Region";
       };
       "csm_email": {
         type: "string";
+        display_name: "CSM Email";
       };
     };
       };
@@ -80,27 +88,38 @@ declare module "@databricks/appkit-ui/react" {
         measures: {
       "mrr": {
         type: "double";
+        display_name: "Monthly Recurring Revenue";
+        format: "$#,##0.00";
       };
       "arr": {
         type: "double";
+        display_name: "Annual Recurring Revenue";
+        format: "$#,##0.00";
         description: "Annualized contract value across all active subscriptions";
       };
       "new_arr": {
         type: "double";
+        display_name: "New ARR";
+        format: "$#,##0.00";
       };
       "churned_arr": {
         type: "double";
+        display_name: "Churned ARR";
+        format: "$#,##0.00";
       };
     };
         dimensions: {
       "region": {
         type: "string";
+        display_name: "Region";
       };
       "segment": {
         type: "string";
+        display_name: "Customer Segment";
       };
       "created_at": {
         type: "timestamp_ltz";
+        display_name: "Subscription Start";
         time_grain: readonly ["day", "hour", "minute", "month", "quarter", "week", "year"];
       };
     };

docs/docs/development/type-generation.md

@@ -86,13 +86,13 @@ In blocking mode the generator starts a stopped warehouse, waits (bounded) for i
 
 ## Metric-view types
 
-`generate-types` (and the Vite plugin) emit metric-view types **additively** — there is no separate command. When a `config/queries/metric-views.json` file is present, the same run that generates your query types also DESCRIBEs each declared [UC Metric View](../plugins/analytics.md) and writes `metric-views.d.ts` into `shared/appkit-types/`:
+`generate-types` (and the Vite plugin) emit metric-view types **additively** — there is no separate command. When a `config/metric-views/definitions.json` file is present, the same run that generates your query types also DESCRIBEs each declared [UC Metric View](../plugins/analytics.md) and writes `metric-views.d.ts` into `shared/appkit-types/`:
 
 - `metric-views.d.ts` — augments the `MetricRegistry` interface so `useMetricView('<key>', …)` is autocompleted and type-checked. Each view's measures, dimensions, and their semantic metadata (SQL type, display name, format, time grains) are encoded at the type level.
 
-If `metric-views.json` is absent the metric path stays dormant (nothing is emitted). When present it follows the **same** warehouse-readiness contract as query types: in the default non-blocking run a view that can't be described yet — a cold warehouse, or a bad/unreachable source — is written with permissive types and a warning, while under `--wait` that same situation fails the build so CI never ships incomplete metric types. A malformed `metric-views.json` (invalid JSON, or a source that isn't a three-part UC FQN) fails fast in every mode.
+If `config/metric-views/definitions.json` is absent the metric path stays dormant (nothing is emitted). When present it follows the **same** warehouse-readiness contract as query types: in the default non-blocking run a view that can't be described yet — a cold warehouse, or a bad/unreachable source — is written with permissive types and a warning, while under `--wait` that same situation fails the build so CI never ships incomplete metric types. A malformed `definitions.json` (invalid JSON, or a source that isn't a three-part UC FQN) fails fast in every mode.
 
-`metric-views.json` is keyed by metric key; each entry names the three-part UC FQN of the view and, optionally, the executor it runs as (`app_service_principal`, the default, or `user`):
+`definitions.json` is keyed by metric key; each entry names the three-part UC FQN of the view and, optionally, the executor it runs as (`app_service_principal`, the default, or `user`):
 
 ```json
 {