refactor(appkit-ui): extract MetricFilter vocabulary + toMetricFilter builder to /js

Move the twelve-operator MetricFilter grammar out of react/hooks/types.ts into a
canonical, framework-agnostic js/metric-filter/ module and add a toMetricFilter
builder that compiles a { dimension -> value(s) } shorthand into a MetricFilter
(scalar -> equals, array -> in, omit undefined/empty). react/hooks/types.ts now
re-exports the types so the /react public surface and UseMetricViewOptions.filter
are unchanged. Wire the dev-playground metric-views route's buildFilter onto
toMetricFilter, keeping only the app-specific cross-filter facet-exclusion local.

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

Author: atilafassina

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

@@ -1,4 +1,9 @@
-import { formatLabel, formatValue } from "@databricks/appkit-ui/js";
+import {
+  formatLabel,
+  formatValue,
+  type MetricFilter,
+  toMetricFilter,
+} from "@databricks/appkit-ui/js";
 import {
   Badge,
   BarChart,
@@ -10,8 +15,6 @@ import {
   CardTitle,
   DonutChart,
   LineChart,
-  type MetricFilter,
-  type MetricPredicate,
   Select,
   SelectContent,
   SelectItem,
@@ -66,20 +69,22 @@ const ALL = "__all__";
  * *cross*-filter rather than a global filter: the by-region chart keeps every
  * region visible when a region is selected (so you can pick another), while the
  * charts grouped by *other* dimensions narrow to that region.
+ *
+ * The map-to-`MetricFilter` compilation itself is the SDK's `toMetricFilter`
+ * (from `@databricks/appkit-ui/js`) — this wrapper only adds the cross-filter
+ * facet-exclusion, which is app-specific and stays local.
  */
 function buildFilter(
   selection: Selection,
   exclude?: FilterDimension,
 ): MetricFilter | undefined {
-  const predicates: MetricPredicate[] = [];
+  const shorthand: Record<string, string> = {};
   for (const dimension of FILTER_DIMENSIONS) {
     const value = selection[dimension];
     if (dimension === exclude || value === undefined) continue;
-    predicates.push({ member: dimension, operator: "equals", values: [value] });
+    shorthand[dimension] = value;
   }
-  if (predicates.length === 0) return undefined;
-  if (predicates.length === 1) return predicates[0];
-  return { and: predicates };
+  return toMetricFilter(shorthand);
 }
 
 /**

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

@@ -13,4 +13,5 @@ export * from "./arrow";
 export * from "./config";
 export * from "./constants";
 export * from "./format";
+export * from "./metric-filter";
 export * from "./sse";

packages/appkit-ui/src/js/metric-filter/index.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, test } from "vitest";
+import { type MetricFilter, toMetricFilter } from "./index";
+
+describe("toMetricFilter", () => {
+  test("returns undefined for an empty selection", () => {
+    expect(toMetricFilter({})).toBeUndefined();
+  });
+
+  test("omits members with undefined values", () => {
+    expect(toMetricFilter({ region: undefined })).toBeUndefined();
+    expect(toMetricFilter({ region: undefined, segment: "SMB" })).toEqual({
+      member: "segment",
+      operator: "equals",
+      values: ["SMB"],
+    });
+  });
+
+  test("omits members with empty-array values", () => {
+    expect(toMetricFilter({ region: [] })).toBeUndefined();
+  });
+
+  test("compiles a single scalar member to a bare equals predicate", () => {
+    expect(toMetricFilter({ region: "EMEA" })).toEqual({
+      member: "region",
+      operator: "equals",
+      values: ["EMEA"],
+    });
+  });
+
+  test("compiles a numeric scalar to an equals predicate", () => {
+    expect(toMetricFilter({ tier: 2 })).toEqual({
+      member: "tier",
+      operator: "equals",
+      values: [2],
+    });
+  });
+
+  test("compiles an array member to an in predicate", () => {
+    expect(toMetricFilter({ region: ["EMEA", "APAC"] })).toEqual({
+      member: "region",
+      operator: "in",
+      values: ["EMEA", "APAC"],
+    });
+  });
+
+  test("AND-groups multiple members, mixing equals and in", () => {
+    expect(
+      toMetricFilter({ region: ["EMEA", "APAC"], segment: "SMB" }),
+    ).toEqual({
+      and: [
+        { member: "region", operator: "in", values: ["EMEA", "APAC"] },
+        { member: "segment", operator: "equals", values: ["SMB"] },
+      ],
+    });
+  });
+
+  test("copies array values rather than aliasing the caller's array", () => {
+    const values = ["EMEA", "APAC"];
+    const filter = toMetricFilter({ region: values });
+    // A single member compiles to a bare predicate (has `values`), not a group.
+    if (!filter || !("values" in filter)) {
+      throw new Error("expected a leaf predicate with values");
+    }
+    expect(filter.values).toEqual(values);
+    expect(filter.values).not.toBe(values);
+  });
+
+  test("produces a MetricFilter assignable to the exported type", () => {
+    const filter: MetricFilter | undefined = toMetricFilter({ region: "EMEA" });
+    expect(filter).toBeDefined();
+  });
+});

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

@@ -0,0 +1,99 @@
+// ────────────────────────────────────────────────────────────────────────────
+// Metric filter vocabulary + builder.
+//
+// Pure, framework-agnostic. Lives on the `/js` axis because a `MetricFilter` is
+// plain data — a Node script, an SSR pass, or a test can build one without React
+// in the graph. The React `useMetricView` hook re-exports these types from
+// `@databricks/appkit-ui/react` so its public surface is unchanged.
+//
+// **Kept in sync with appkit `plugins/analytics/types.ts`** — appkit-ui cannot
+// depend on appkit, so this mirrors the twelve-operator filter grammar by hand.
+// ────────────────────────────────────────────────────────────────────────────
+
+/** v1 filter operator vocabulary — exactly twelve names. */
+export type MetricFilterOperatorName =
+  | "equals"
+  | "notEquals"
+  | "in"
+  | "notIn"
+  | "gt"
+  | "gte"
+  | "lt"
+  | "lte"
+  | "contains"
+  | "notContains"
+  | "set"
+  | "notSet";
+
+/** A single filter predicate — the leaf node of the recursive {@link MetricFilter} tree. */
+export interface MetricPredicate {
+  member: string;
+  operator: MetricFilterOperatorName;
+  values?: ReadonlyArray<string | number>;
+}
+
+/** Recursive filter expression: a leaf {@link MetricPredicate} or an `and`/`or` group. */
+export type MetricFilter =
+  | MetricPredicate
+  | { and: ReadonlyArray<MetricFilter> }
+  | { or: ReadonlyArray<MetricFilter> };
+
+/**
+ * Shorthand map of `dimension -> selected value(s)` that {@link toMetricFilter}
+ * compiles into a {@link MetricFilter}. A member is dropped when its value is
+ * `undefined` or an empty array, so a partially-filled filter-bar selection maps
+ * straight to "no predicate for that dimension".
+ */
+export type MetricFilterShorthand = Record<
+  string,
+  string | number | ReadonlyArray<string | number> | undefined
+>;
+
+/**
+ * Compile a `{ dimension -> value(s) }` shorthand into a {@link MetricFilter} —
+ * the equality/membership case a filter bar, dropdown set, or clicked data point
+ * produces. Scalar values become an `equals` predicate; array values become an
+ * `in` predicate. Members with `undefined` or empty-array values are omitted.
+ *
+ * Returns a bare {@link MetricPredicate} for a single member, an `and` group for
+ * several, and `undefined` when nothing is selected (so the caller can pass it
+ * straight to `useMetricView`'s optional `filter`, which omits the field when
+ * `undefined`). For operators beyond equality/membership (ranges, `contains`,
+ * `set`), build the {@link MetricFilter} tree directly.
+ *
+ * @example
+ * ```typescript
+ * toMetricFilter({ region: "EMEA" });
+ * // → { member: "region", operator: "equals", values: ["EMEA"] }
+ *
+ * toMetricFilter({ region: ["EMEA", "APAC"], segment: "SMB" });
+ * // → { and: [
+ * //     { member: "region", operator: "in", values: ["EMEA", "APAC"] },
+ * //     { member: "segment", operator: "equals", values: ["SMB"] },
+ * //   ] }
+ *
+ * toMetricFilter({ region: undefined }); // → undefined
+ * ```
+ */
+export function toMetricFilter(
+  selection: MetricFilterShorthand,
+): MetricFilter | undefined {
+  const predicates: MetricPredicate[] = [];
+  for (const member of Object.keys(selection)) {
+    const value = selection[member];
+    if (value === undefined) continue;
+    if (Array.isArray(value)) {
+      if (value.length === 0) continue;
+      predicates.push({ member, operator: "in", values: [...value] });
+    } else {
+      predicates.push({
+        member,
+        operator: "equals",
+        values: [value as string | number],
+      });
+    }
+  }
+  if (predicates.length === 0) return undefined;
+  if (predicates.length === 1) return predicates[0];
+  return { and: predicates };
+}

packages/appkit-ui/src/react/hooks/types.ts

@@ -317,40 +317,17 @@ export type InferMetricRow<K> = K extends AugmentedRegistry<MetricRegistry>
     : Record<string, unknown>
   : Record<string, unknown>;
 
-// ────────────────────────────────────────────────────────────────────────────
-// Metric filter vocabulary.
-//
-// **Kept in sync with appkit `plugins/analytics/types.ts`** — appkit-ui cannot
-// depend on appkit, so this mirrors the twelve-operator filter grammar by hand.
-// ────────────────────────────────────────────────────────────────────────────
-
-/** v1 filter operator vocabulary — exactly twelve names. */
-export type MetricFilterOperatorName =
-  | "equals"
-  | "notEquals"
-  | "in"
-  | "notIn"
-  | "gt"
-  | "gte"
-  | "lt"
-  | "lte"
-  | "contains"
-  | "notContains"
-  | "set"
-  | "notSet";
-
-/** A single filter predicate — the leaf node of the recursive {@link MetricFilter} tree. */
-export interface MetricPredicate {
-  member: string;
-  operator: MetricFilterOperatorName;
-  values?: ReadonlyArray<string | number>;
-}
-
-/** Recursive filter expression: a leaf {@link MetricPredicate} or an `and`/`or` group. */
-export type MetricFilter =
-  | MetricPredicate
-  | { and: ReadonlyArray<MetricFilter> }
-  | { or: ReadonlyArray<MetricFilter> };
+// The metric-filter vocabulary is pure data (no React), so it lives canonically
+// on the `/js` axis. Re-export it here so the `/react` public surface — and
+// `UseMetricViewOptions.filter` below — is unchanged. The runtime builder
+// `toMetricFilter` is available from `@databricks/appkit-ui/js`.
+export type {
+  MetricFilter,
+  MetricFilterOperatorName,
+  MetricPredicate,
+} from "@/js";
+
+import type { MetricFilter } from "@/js";
 
 /** Options for configuring a `useMetricView` query. */
 export interface UseMetricViewOptions<K extends MetricKey = MetricKey> {