feat: export notify for write-back feat

Author: atilafassina

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

@@ -9,12 +9,14 @@ import {
   BarChart,
   Button,
   Card,
+  CardAction,
   CardContent,
   CardDescription,
   CardHeader,
   CardTitle,
   DonutChart,
   LineChart,
+  notify,
   Select,
   SelectContent,
   SelectItem,
@@ -30,6 +32,7 @@ import {
   useMetricView,
 } from "@databricks/appkit-ui/react";
 import { createFileRoute } from "@tanstack/react-router";
+import { FilterIcon } from "lucide-react";
 import { useCallback, useMemo, useState } from "react";
 import { Header } from "@/components/layout/header";
 
@@ -87,6 +90,47 @@ function buildFilter(
   return toMetricFilter(shorthand);
 }
 
+/**
+ * The dimensions actually shaping a card's data, given the shared selection and
+ * the card's own excluded dimension. Mirrors `buildFilter`'s facet-exclusion so
+ * the badge tells the truth per-card: the ARR-by-region card excludes `region`,
+ * so it never claims a region filter it deliberately ignores.
+ */
+function appliedDimensions(
+  selection: Selection,
+  exclude?: FilterDimension,
+): FilterDimension[] {
+  return FILTER_DIMENSIONS.filter(
+    (dimension) => dimension !== exclude && selection[dimension] !== undefined,
+  );
+}
+
+/**
+ * Header badge that makes a card explicit about which filters shaped its data.
+ * Renders nothing when the card is unfiltered, so an unsliced card stays clean.
+ * Placed in `CardAction` (top-right of the header) via the caller.
+ */
+function FilterBadge({
+  selection,
+  exclude,
+}: {
+  selection: Selection;
+  exclude?: FilterDimension;
+}) {
+  const applied = appliedDimensions(selection, exclude);
+  if (applied.length === 0) return null;
+  return (
+    <Badge variant="secondary" className="gap-1">
+      <FilterIcon className="size-3" aria-hidden />
+      {applied
+        .map(
+          (dimension) => `${formatLabel(dimension)}: ${selection[dimension]}`,
+        )
+        .join(" · ")}
+    </Badge>
+  );
+}
+
 /**
  * Loading / error / empty state shared by every visual card. Returns `null`
  * once data has rows so the caller renders the visual.
@@ -313,6 +357,11 @@ function MetricViewsRoute() {
               <CardDescription>
                 revenue · arr · grouped by region
               </CardDescription>
+              <CardAction>
+                {/* Excludes `region` — same facet-exclusion as this card's
+                    filter, so it never claims the region slice it ignores. */}
+                <FilterBadge selection={selection} exclude="region" />
+              </CardAction>
             </CardHeader>
             <CardContent>
               <VisualStatus
@@ -329,7 +378,6 @@ function MetricViewsRoute() {
                     xKey="region"
                     yKey="arr"
                     height={280}
-                    title="Annual recurring revenue by region"
                     onDataClick={(d) => setDimension("region", d.name)}
                     selected={selection.region}
                   />
@@ -344,6 +392,9 @@ function MetricViewsRoute() {
               <CardDescription>
                 revenue · arr · grouped by segment
               </CardDescription>
+              <CardAction>
+                <FilterBadge selection={selection} exclude="segment" />
+              </CardAction>
             </CardHeader>
             <CardContent>
               <VisualStatus
@@ -362,7 +413,6 @@ function MetricViewsRoute() {
                     height={280}
                     innerRadius={55}
                     showLegend
-                    title="Annual recurring revenue by segment"
                     onDataClick={(d) => setDimension("segment", d.name)}
                     selected={selection.segment}
                   />
@@ -378,6 +428,11 @@ function MetricViewsRoute() {
             <CardDescription>
               revenue · measures {TREND_MEASURES.join(", ")} · grouped by month
             </CardDescription>
+            <CardAction>
+              {/* No `exclude` — the trend groups by time, so it applies the
+                  full selection (both region and segment narrow it). */}
+              <FilterBadge selection={selection} />
+            </CardAction>
           </CardHeader>
           <CardContent>
             <VisualStatus
@@ -395,7 +450,45 @@ function MetricViewsRoute() {
                   yKey={[...TREND_MEASURES]}
                   height={320}
                   showLegend
-                  title="ARR vs MRR over time"
+                  // 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>
@@ -409,6 +502,11 @@ function MetricViewsRoute() {
               Click a row to filter every visual by that region — click again
               (or a chip above) to clear.
             </CardDescription>
+            <CardAction>
+              {/* Grouped by region, so it excludes `region` (same as the region
+                  bar) — a segment filter still narrows it. */}
+              <FilterBadge selection={selection} exclude="region" />
+            </CardAction>
           </CardHeader>
           <CardContent>
             <VisualStatus

packages/appkit-ui/src/react/charts/__tests__/options.test.ts

@@ -28,6 +28,7 @@ interface EChartsOption {
     showSymbol?: boolean;
     symbol?: string;
     symbolSize?: number;
+    triggerLineEvent?: boolean;
     areaStyle?: { opacity: number };
     stack?: string;
     itemStyle?: { borderRadius?: number[] };
@@ -200,6 +201,65 @@ describe("buildCartesianOption", () => {
       expect(opt.series[0].smooth).toBe(false);
       expect(opt.series[0].showSymbol).toBe(false);
     });
+
+    test("applies symbolSize to line series (not just scatter)", () => {
+      const ctx = createBaseContext();
+      const opt = asOption(
+        buildCartesianOption({
+          ...ctx,
+          chartType: "line",
+          isTimeSeries: false,
+          stacked: false,
+          smooth: true,
+          showSymbol: true,
+          symbolSize: 14,
+        }),
+      );
+
+      expect(opt.series[0].symbolSize).toBe(14);
+    });
+
+    test("sets triggerLineEvent only when interactive", () => {
+      const ctx = createBaseContext();
+      const base = {
+        ...ctx,
+        chartType: "line" as const,
+        isTimeSeries: false,
+        stacked: false,
+        smooth: true,
+        showSymbol: true,
+        symbolSize: 8,
+      };
+
+      // Non-interactive line: no triggerLineEvent.
+      expect(
+        asOption(buildCartesianOption(base)).series[0].triggerLineEvent,
+      ).toBeUndefined();
+
+      // Interactive line: whole stroke is clickable.
+      expect(
+        asOption(buildCartesianOption({ ...base, interactive: true })).series[0]
+          .triggerLineEvent,
+      ).toBe(true);
+    });
+
+    test("does not set triggerLineEvent on a bar series even when interactive", () => {
+      const ctx = createBaseContext();
+      const opt = asOption(
+        buildCartesianOption({
+          ...ctx,
+          chartType: "bar",
+          isTimeSeries: false,
+          stacked: false,
+          smooth: false,
+          showSymbol: false,
+          symbolSize: 8,
+          interactive: true,
+        }),
+      );
+
+      expect(opt.series[0].triggerLineEvent).toBeUndefined();
+    });
   });
 
   describe("area chart", () => {

packages/appkit-ui/src/react/charts/base.tsx

@@ -232,6 +232,15 @@ export function BaseChart({
 
   const ui = useChartUITokens();
 
+  // Only the *presence* of a click handler shapes the option (it flips
+  // `triggerLineEvent`/`symbolSize` on line/area). Depend on this boolean, not
+  // the handler reference — consumers pass an inline `onDataClick`, whose
+  // identity changes every render, so depending on the reference would rebuild
+  // the whole option object on every parent re-render (e.g. each SSE tick). The
+  // `onEvents` memo below still depends on `onDataClick` itself — it needs the
+  // real function.
+  const interactive = !!onDataClick;
+
   // Store ECharts instance directly to avoid stale ref issues on unmount
   const echartsInstanceRef = useRef<ECharts | null>(null);
 
@@ -348,6 +357,9 @@ export function BaseChart({
         smooth,
         showSymbol,
         symbolSize,
+        // A click handler turns on `triggerLineEvent` for line/area so the
+        // whole stroke is clickable, not just symbols.
+        interactive,
       });
     }
 
@@ -375,6 +387,7 @@ export function BaseChart({
     max,
     customOptions,
     selected,
+    interactive,
   ]);
 
   // Build the ECharts event map only when a click handler is provided. Memoized

packages/appkit-ui/src/react/charts/options.ts

@@ -29,6 +29,12 @@ export interface CartesianContext extends OptionBuilderContext {
   smooth: boolean;
   showSymbol: boolean;
   symbolSize: number;
+  /**
+   * Whether a click handler is attached. When true, line/area series set
+   * `triggerLineEvent` so a click anywhere on the stroke fires (not just on a
+   * symbol) — otherwise clicking a thin line is nearly impossible to land.
+   */
+  interactive?: boolean;
 }
 
 // ============================================================================
@@ -331,11 +337,19 @@ export function buildCartesianOption(
   ctx: CartesianContext,
 ): Record<string, unknown> {
   const ui = ctx.ui ?? FALLBACK_UI_TOKENS;
-  const { chartType, isTimeSeries, stacked, smooth, showSymbol, symbolSize } =
-    ctx;
+  const {
+    chartType,
+    isTimeSeries,
+    stacked,
+    smooth,
+    showSymbol,
+    symbolSize,
+    interactive,
+  } = ctx;
   const hasMultipleSeries = ctx.yFields.length > 1;
   const seriesType = chartType === "area" ? "line" : chartType;
   const isScatter = chartType === "scatter";
+  const isLineLike = chartType === "line" || chartType === "area";
 
   return {
     ...buildBaseOption(ctx),
@@ -378,11 +392,15 @@ export function buildCartesianOption(
         : isTimeSeries
           ? createTimeSeriesData(ctx.xData, ctx.yDataMap[key])
           : ctx.yDataMap[key],
-      smooth: chartType === "line" || chartType === "area" ? smooth : undefined,
-      showSymbol:
-        chartType === "line" || chartType === "area" ? showSymbol : undefined,
+      smooth: isLineLike ? smooth : undefined,
+      showSymbol: isLineLike ? showSymbol : undefined,
       symbol: isScatter ? "circle" : undefined,
-      symbolSize: isScatter ? symbolSize : undefined,
+      // Symbol size now applies to line/area too (previously scatter-only), so
+      // an interactive line can present a clickable point, not just a hairline.
+      symbolSize: isScatter || isLineLike ? symbolSize : undefined,
+      // Fire click events along the whole line stroke, not only on symbols,
+      // when the chart is interactive. No effect on non-line series.
+      triggerLineEvent: isLineLike && interactive ? true : undefined,
       areaStyle: chartType === "area" ? { opacity: 0.3 } : undefined,
       stack: stacked && chartType === "area" ? "total" : undefined,
       itemStyle:

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

@@ -41,6 +41,7 @@ export * from "./sheet";
 export * from "./sidebar";
 export * from "./skeleton";
 export * from "./slider";
+export * from "./notify";
 export * from "./sonner";
 export * from "./spinner";
 export * from "./switch";

packages/appkit-ui/src/react/ui/notify.ts

@@ -0,0 +1,42 @@
+import type { ReactNode } from "react";
+import { toast } from "sonner";
+
+/** Options for a {@link notify} toast — a curated subset of sonner's surface. */
+export interface NotifyOptions {
+  /** Secondary line under the title. */
+  description?: ReactNode;
+  /** Auto-dismiss delay in ms. Omit for sonner's default; `Infinity` to make it sticky. */
+  duration?: number;
+}
+
+/**
+ * Fire a transient toast through the app's mounted `<Toaster />` — the same
+ * sonner surface `ResourceStatusIndicator` renders warehouse-readiness into.
+ *
+ * This is a curated wrapper so app code never imports sonner directly: it
+ * exposes only a title + `{ description, duration }`, not sonner's full option
+ * bag. Requires a `<Toaster />` (or `<ResourceStatusIndicator />`) mounted in
+ * the tree; without one the call is a no-op.
+ *
+ * @example
+ * ```tsx
+ * notify.message("Write back: Arr · Apr 2026 · $8,100,000");
+ * notify.success("Saved", { description: "Row written back to the source." });
+ * ```
+ */
+export const notify = {
+  /** Neutral message toast. */
+  message: (title: ReactNode, options?: NotifyOptions) =>
+    toast(title, options),
+  /** Informational toast. */
+  info: (title: ReactNode, options?: NotifyOptions) => toast.info(title, options),
+  /** Success toast. */
+  success: (title: ReactNode, options?: NotifyOptions) =>
+    toast.success(title, options),
+  /** Warning toast. */
+  warning: (title: ReactNode, options?: NotifyOptions) =>
+    toast.warning(title, options),
+  /** Error toast. */
+  error: (title: ReactNode, options?: NotifyOptions) =>
+    toast.error(title, options),
+};