@agent-native/toolkit 0.213.1 → 0.216.0

package/src/app/chat/chat/widgets/DataChartWidget.spec.tsx

@@ -0,0 +1,432 @@
+// @vitest-environment happy-dom
+
+import { AgentNativeI18nProvider } from "@agent-native/core/client/i18n";
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { createToolkitI18nCatalog } from "../../../i18n.js";
+import type {
+  DataWidgetAction,
+  DataWidgetChartAction,
+  DataWidgetDisplayAction,
+} from "./data-widget-types.js";
+import { DataChartWidget } from "./DataChartWidget.js";
+
+const mocks = vi.hoisted(() => ({
+  writeClipboardText: vi.fn(),
+  toast: vi.fn(),
+}));
+
+vi.mock("@agent-native/toolkit/clipboard", () => ({
+  writeClipboardText: mocks.writeClipboardText,
+}));
+
+vi.mock("../../../../hooks/use-toast.js", () => ({ toast: mocks.toast }));
+
+vi.mock("./DataChartRenderer.js", () => ({
+  DataChartRenderer: ({
+    chart,
+  }: {
+    chart: {
+      contentHeight?: number;
+      contentPadding?: number;
+      labelFontFamily?: string;
+      labelFontSize?: number;
+    };
+  }) => (
+    <div
+      data-testid="chart-surface"
+      data-content-height={chart.contentHeight}
+      data-content-padding={chart.contentPadding}
+      data-label-font-family={chart.labelFontFamily}
+      data-label-font-size={chart.labelFontSize}
+    />
+  ),
+}));
+
+const toolkitI18nCatalog = createToolkitI18nCatalog({ messages: {} });
+const initialBasePath = process.env.VITE_APP_BASE_PATH;
+const roots: Root[] = [];
+
+async function renderWidget(
+  chartActions?: DataWidgetChartAction[],
+  displayActions: DataWidgetDisplayAction[] = [
+    {
+      id: "details",
+      type: "link",
+      label: "Open details",
+      href: "/reports/1/details",
+    },
+    {
+      id: "query",
+      type: "copy",
+      label: "Copy query",
+      text: "select count(*)",
+    },
+    {
+      id: "unsafe",
+      type: "link",
+      label: "Unsafe",
+      href: "javascript:alert(1)",
+    },
+  ],
+  sampled = false,
+  chartDataCount = 1,
+  truncated = false,
+) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const root = createRoot(container);
+  roots.push(root);
+
+  await act(async () => {
+    root.render(
+      <AgentNativeI18nProvider
+        catalog={toolkitI18nCatalog}
+        persistPreference={false}
+      >
+        <DataChartWidget
+          chart={{
+            type: "bar",
+            title: "Responses by day",
+            xKey: "day",
+            series: [{ key: "count", label: "Responses" }],
+            data: Array.from({ length: chartDataCount }, (_, index) => ({
+              day: `Day ${index}`,
+              count: index,
+            })),
+            sampled,
+            truncated,
+            actions: chartActions,
+          }}
+          display={{
+            primaryAction: {
+              label: "Open report",
+              href: "/reports/1?tab=chart",
+            },
+            sources: [
+              {
+                id: "warehouse",
+                label: "Warehouse",
+                href: "/sources/warehouse",
+              },
+              { id: "local", label: "Local data" },
+            ],
+            actions: displayActions,
+          }}
+        />
+      </AgentNativeI18nProvider>,
+    );
+  });
+
+  return container;
+}
+
+async function openActionsMenu(container: HTMLElement) {
+  const trigger = container.querySelector<HTMLButtonElement>(
+    'button[aria-label="Chart actions"]',
+  );
+  expect(trigger).not.toBeNull();
+
+  await act(async () => {
+    trigger?.dispatchEvent(
+      new PointerEvent("pointerdown", {
+        bubbles: true,
+        button: 0,
+        pointerType: "mouse",
+      }),
+    );
+    await Promise.resolve();
+  });
+
+  return document.querySelector<HTMLElement>("[role=menu]");
+}
+
+describe("DataChartWidget display contract", () => {
+  beforeEach(() => {
+    vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+    process.env.VITE_APP_BASE_PATH = "/mounted";
+    window.history.replaceState({}, "", "/chat");
+    mocks.writeClipboardText.mockResolvedValue(true);
+  });
+
+  afterEach(() => {
+    for (const root of roots.splice(0)) {
+      act(() => root.unmount());
+    }
+    document.body.innerHTML = "";
+    window.history.replaceState({}, "", "/");
+    process.env.VITE_APP_BASE_PATH = initialBasePath;
+    mocks.writeClipboardText.mockReset();
+    mocks.toast.mockReset();
+    vi.unstubAllGlobals();
+  });
+
+  it("renders source chips and navigates safe chart links", async () => {
+    const container = await renderWidget();
+    const primary = Array.from(container.querySelectorAll("a")).find((link) =>
+      link.textContent?.includes("Open report"),
+    );
+    const source = Array.from(container.querySelectorAll("a")).find((link) =>
+      link.textContent?.includes("Warehouse"),
+    );
+
+    expect(primary?.getAttribute("href")).toBe("/mounted/reports/1?tab=chart");
+    expect(source?.getAttribute("href")).toBe("/mounted/sources/warehouse");
+    expect(container.textContent).toContain("Local data");
+
+    await act(async () => {
+      primary?.dispatchEvent(
+        new MouseEvent("click", { bubbles: true, cancelable: true, button: 0 }),
+      );
+    });
+
+    expect(window.location.pathname).toBe("/mounted/reports/1");
+    expect(window.location.search).toBe("?tab=chart");
+  });
+
+  it("announces incomplete chart data and stays quiet for complete data", async () => {
+    const cappedContainer = await renderWidget(
+      undefined,
+      undefined,
+      false,
+      201,
+    );
+    const cappedDisclosure = cappedContainer.querySelector('[role="status"]');
+
+    expect(cappedDisclosure?.textContent).toBe(
+      "This chart shows only some of the available rows.",
+    );
+
+    const sampledContainer = await renderWidget(undefined, undefined, true);
+    expect(sampledContainer.querySelector('[role="status"]')?.textContent).toBe(
+      "This chart shows only some of the available rows.",
+    );
+
+    const sampledAndCappedContainer = await renderWidget(
+      undefined,
+      undefined,
+      true,
+      201,
+    );
+    expect(
+      sampledAndCappedContainer.querySelector('[role="status"]')?.textContent,
+    ).toBe("This chart shows only some of the available rows.");
+
+    const clampedContainer = await renderWidget(
+      undefined,
+      undefined,
+      true,
+      200,
+      true,
+    );
+    expect(clampedContainer.querySelector('[role="status"]')?.textContent).toBe(
+      "This chart shows only some of the available rows.",
+    );
+
+    const completeContainer = await renderWidget();
+    expect(completeContainer.querySelector('[role="status"]')).toBeNull();
+  });
+
+  it("opens overflow links and copies the requested text", async () => {
+    const container = await renderWidget();
+    const menu = await openActionsMenu(container);
+    expect(menu).not.toBeNull();
+    expect(menu?.textContent).toContain("Open details");
+    expect(menu?.textContent).toContain("Copy query");
+    expect(menu?.textContent).not.toContain("Unsafe");
+
+    const details = Array.from(menu?.querySelectorAll("a") ?? []).find((link) =>
+      link.textContent?.includes("Open details"),
+    );
+    expect(details?.getAttribute("href")).toBe("/mounted/reports/1/details");
+
+    await act(async () => {
+      details?.dispatchEvent(
+        new MouseEvent("click", { bubbles: true, cancelable: true, button: 0 }),
+      );
+    });
+    expect(window.location.pathname).toBe("/mounted/reports/1/details");
+
+    const secondContainer = await renderWidget();
+    const secondMenu = await openActionsMenu(secondContainer);
+    const copy = Array.from(
+      secondMenu?.querySelectorAll<HTMLElement>("[role=menuitem]") ?? [],
+    ).find((item) => item.textContent?.includes("Copy query"));
+
+    await act(async () => {
+      copy?.click();
+      await Promise.resolve();
+    });
+
+    expect(mocks.writeClipboardText).toHaveBeenCalledWith("select count(*)");
+    expect(mocks.toast).toHaveBeenCalledWith({ title: "Copied" });
+  });
+
+  it("renders actions attached to the chart payload", async () => {
+    const container = await renderWidget([
+      {
+        label: "Explore results",
+        href: "/reports/1/explore",
+        icon: "explore",
+      },
+      {
+        label: "Download image",
+        href: "/reports/1/image",
+        icon: "camera",
+      },
+      {
+        label: "Save to notebook",
+        href: "/notebooks/new",
+        icon: "notebook",
+      },
+    ]);
+    const menu = await openActionsMenu(container);
+
+    expect(menu?.textContent).toContain("Explore results");
+    expect(menu?.textContent).toContain("Download image");
+    expect(menu?.textContent).toContain("Save to notebook");
+    expect(
+      menu?.querySelector('a[href="/mounted/reports/1/explore"] svg'),
+    ).not.toBeNull();
+    expect(
+      menu?.querySelector('a[href="/mounted/reports/1/image"] svg'),
+    ).not.toBeNull();
+    expect(
+      menu?.querySelector('a[href="/mounted/notebooks/new"] svg'),
+    ).not.toBeNull();
+  });
+
+  it("renders an icon action directly with an accessible label", async () => {
+    const container = await renderWidget([
+      {
+        label: "Download image",
+        href: "/reports/1/image",
+        icon: "camera",
+        presentation: "icon",
+      },
+    ]);
+    const directAction = container.querySelector<HTMLAnchorElement>(
+      'a[aria-label="Download image"]',
+    );
+    const menu = await openActionsMenu(container);
+
+    expect(directAction?.getAttribute("href")).toBe("/mounted/reports/1/image");
+    expect(directAction?.getAttribute("title")).toBe("Download image");
+    expect(directAction?.querySelector("svg")).not.toBeNull();
+    expect(menu?.textContent).not.toContain("Download image");
+    expect(menu?.textContent).toContain("Open details");
+    expect(menu?.textContent).toContain("Copy query");
+  });
+
+  it("hides the overflow control when all actions are direct icons", async () => {
+    const container = await renderWidget(
+      [],
+      [
+        {
+          id: "direct-download",
+          type: "link",
+          label: "Download image",
+          href: "/reports/1/image",
+          icon: "camera",
+          presentation: "icon",
+        },
+      ],
+    );
+
+    expect(
+      container.querySelector('a[aria-label="Download image"]'),
+    ).not.toBeNull();
+    expect(
+      container.querySelector('button[aria-label="Chart actions"]'),
+    ).toBeNull();
+  });
+
+  it("keeps chart actions as links when payload metadata includes a type", async () => {
+    const container = await renderWidget([
+      {
+        type: "copy",
+        label: "Explore results",
+        href: "/reports/1/explore",
+      } as DataWidgetAction,
+    ]);
+    const menu = await openActionsMenu(container);
+
+    expect(
+      menu?.querySelector('a[href="/mounted/reports/1/explore"]'),
+    ).not.toBeNull();
+  });
+
+  it("does not render executable primary-action URLs", async () => {
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    const root = createRoot(container);
+    roots.push(root);
+
+    await act(async () => {
+      root.render(
+        <AgentNativeI18nProvider
+          catalog={toolkitI18nCatalog}
+          persistPreference={false}
+        >
+          <DataChartWidget
+            chart={{
+              type: "bar",
+              xKey: "day",
+              series: [{ key: "count", label: "Count" }],
+              data: [],
+            }}
+            display={{
+              primaryAction: { label: "Unsafe", href: "javascript:alert(1)" },
+            }}
+          />
+        </AgentNativeI18nProvider>,
+      );
+    });
+
+    expect(container.querySelector("a")).toBeNull();
+  });
+
+  it("uses the chart-selected content height without adding body padding", async () => {
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    const root = createRoot(container);
+    roots.push(root);
+
+    await act(async () => {
+      root.render(
+        <AgentNativeI18nProvider
+          catalog={toolkitI18nCatalog}
+          persistPreference={false}
+        >
+          <DataChartWidget
+            chart={{
+              type: "bar",
+              xKey: "day",
+              contentHeight: 400,
+              contentPadding: 16,
+              labelFontFamily: "sans",
+              labelFontSize: 14,
+              series: [{ key: "count", label: "Count" }],
+              data: [],
+            }}
+          />
+        </AgentNativeI18nProvider>,
+      );
+    });
+
+    const frame = container.querySelector(".my-4");
+    const header = frame?.querySelector(".h-12");
+    const chartSurface = frame?.querySelector<HTMLElement>(
+      "[data-testid=chart-surface]",
+    );
+    expect(frame?.className).toContain("rounded-[3px]");
+    expect(header?.className).toContain("border-b");
+    expect(chartSurface?.dataset.contentHeight).toBe("400");
+    expect(chartSurface?.dataset.contentPadding).toBe("16");
+    expect(chartSurface?.dataset.labelFontFamily).toBe("sans");
+    expect(chartSurface?.dataset.labelFontSize).toBe("14");
+    expect(frame?.querySelector(".p-3")).toBeNull();
+  });
+});

package/src/app/chat/chat/widgets/DataChartWidget.ssr.spec.tsx

@@ -18,11 +18,36 @@ describe("DataChartWidget SSR", () => {
           series: [{ key: "count", label: "Count" }],
           data: [{ day: "2026-06-17", count: 3 }],
         }}
+        display={{
+          primaryAction: {
+            label: "Open report",
+            href: "https://reports.example.com/one",
+          },
+        }}
       />,
     );
 
     expect(html).toContain("Submissions");
     expect(html).toContain("Chart");
     expect(html).not.toContain("Loading chart");
+    expect(html).toContain('href="https://reports.example.com/one"');
+
+    const mailtoHtml = renderToString(
+      <DataChartWidget
+        chart={{
+          type: "bar",
+          xKey: "day",
+          series: [{ key: "count", label: "Count" }],
+          data: [],
+        }}
+        display={{
+          primaryAction: {
+            label: "Email report",
+            href: "mailto:reports@example.com",
+          },
+        }}
+      />,
+    );
+    expect(mailtoHtml).toContain('href="mailto:reports@example.com"');
   });
 });

package/src/app/chat/chat/widgets/DataChartWidget.tsx

@@ -1,12 +1,15 @@
-import {
-  DEFAULT_LOCALE,
-  useOptionalLocale,
-  useT,
-} from "@agent-native/core/client/i18n";
-import { IconChartBar } from "@tabler/icons-react";
+import { useT } from "@agent-native/core/client/i18n";
+import { DATA_WIDGET_MAX_CHART_POINTS } from "@agent-native/core/data-widgets";
 import { lazy, Suspense, useEffect, useState } from "react";
 
-import type { DataChartWidget as DataChartWidgetData } from "./data-widget-types.js";
+import type {
+  DataChartWidget as DataChartWidgetData,
+  DataWidgetDisplay,
+} from "./data-widget-types.js";
+import {
+  DataWidgetDisplayControls,
+  DataWidgetSourceChips,
+} from "./DataWidgetDisplayControls.js";
 
 const LazyDataChartRenderer = lazy(() =>
   import("./DataChartRenderer.js").then((module) => ({
@@ -14,47 +17,69 @@ const LazyDataChartRenderer = lazy(() =>
   })),
 );
 
-export function DataChartWidget({ chart }: { chart: DataChartWidgetData }) {
+export function DataChartWidget({
+  chart,
+  display,
+}: {
+  chart: DataChartWidgetData;
+  display?: DataWidgetDisplay;
+}) {
   const t = useT();
-  const locale = useOptionalLocale()?.locale ?? DEFAULT_LOCALE;
   const [mounted, setMounted] = useState(false);
+  const contentHeight = chart.contentHeight;
+  const contentPadding = chart.contentPadding ?? 0;
+  const hasOmittedRows =
+    chart.sampled === true ||
+    chart.truncated === true ||
+    chart.data.length > DATA_WIDGET_MAX_CHART_POINTS;
 
   useEffect(() => {
     setMounted(true);
   }, []);
 
   const fallback = (
-    <div className="flex h-60 items-center justify-center rounded-md bg-muted/30 text-xs text-muted-foreground">
+    <div
+      className={`box-border flex w-full items-center justify-center rounded-md bg-muted/30 text-xs text-muted-foreground ${contentHeight ? "" : "aspect-[16/9]"}`}
+      style={
+        contentHeight !== undefined || contentPadding > 0
+          ? {
+              ...(contentHeight !== undefined
+                ? { height: `${contentHeight}px` }
+                : {}),
+              padding: `${contentPadding}px`,
+            }
+          : undefined
+      }
+    >
       {t("agentChat.widget.chart")}
     </div>
   );
 
   return (
-    <div className="my-1.5 overflow-hidden rounded-lg border border-border bg-background text-foreground shadow-sm">
-      <div className="flex items-center gap-2 border-b border-border px-3 py-2">
-        <IconChartBar className="h-4 w-4 shrink-0 text-muted-foreground" />
-        <div className="min-w-0 flex-1">
-          <div className="truncate text-sm font-medium">
-            {chart.title ?? t("agentChat.widget.dataChart")}
-          </div>
-          <div className="text-[11px] text-muted-foreground">
-            {t("agentChat.widget.points", {
-              count: chart.data.length,
-              formattedCount: chart.data.length.toLocaleString(locale),
-            })}
-            {chart.sampled ? ` ${t("agentChat.widget.sampled")}` : ""}
-          </div>
+    <div className="my-4 overflow-hidden rounded-[3px] border border-border bg-background text-foreground shadow-sm">
+      <div className="flex h-12 items-center gap-2 border-b border-border px-3">
+        <div className="min-w-0 flex-1 truncate text-sm font-medium">
+          {chart.title ?? t("agentChat.widget.dataChart")}
         </div>
+        <DataWidgetDisplayControls
+          display={display}
+          chartActions={chart.actions}
+          variant="secondary"
+        />
       </div>
-      <div className="p-3">
-        {!mounted ? (
-          fallback
-        ) : (
-          <Suspense fallback={fallback}>
-            <LazyDataChartRenderer chart={chart} />
-          </Suspense>
-        )}
-      </div>
+      {!mounted ? (
+        fallback
+      ) : (
+        <Suspense fallback={fallback}>
+          <LazyDataChartRenderer chart={chart} />
+        </Suspense>
+      )}
+      {hasOmittedRows ? (
+        <p className="px-3 pb-3 text-xs text-muted-foreground" role="status">
+          {t("agentChat.widget.chartRowsOmitted")}
+        </p>
+      ) : null}
+      <DataWidgetSourceChips sources={display?.sources ?? []} />
     </div>
   );
 }

package/src/app/chat/chat/widgets/DataInsightsWidget.tsx

@@ -49,12 +49,12 @@ export function DataInsightsWidget({ result }: { result: DataWidgetResult }) {
         </div>
       </div>
       {result.chartSeries ? (
-        <DataChartWidget chart={result.chartSeries} />
+        <DataChartWidget chart={result.chartSeries} display={result.display} />
       ) : null}
       {result.table ? (
         <DataTableWidget
           table={result.table}
-          action={result.display?.primaryAction}
+          display={result.chartSeries ? undefined : result.display}
         />
       ) : null}
     </div>

package/src/app/chat/chat/widgets/DataTableWidget.spec.tsx

@@ -3,7 +3,7 @@
 import { AgentNativeI18nProvider } from "@agent-native/core/client/i18n";
 import React, { act } from "react";
 import { createRoot, type Root } from "react-dom/client";
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import { downloadFile } from "../../../db-admin/export-utils.js";
 import { createToolkitI18nCatalog } from "../../../i18n.js";
@@ -23,7 +23,16 @@ vi.mock("../../../db-admin/export-utils.js", async (importOriginal) => {
 const roots: Root[] = [];
 const initialBasePath = process.env.VITE_APP_BASE_PATH;
 
-async function renderWidget(action: { label: string; href: string }) {
+async function renderWidget(
+  action: { label: string; href: string },
+  display?: {
+    sources?: Array<{ id?: string; label: string; href?: string }>;
+    actions?: Array<
+      | { id?: string; type: "link"; label: string; href: string }
+      | { id?: string; type: "copy"; label: string; text: string }
+    >;
+  },
+) {
   const container = document.createElement("div");
   document.body.appendChild(container);
   const root = createRoot(container);
@@ -36,6 +45,7 @@ async function renderWidget(action: { label: string; href: string }) {
       >
         <DataTableWidget
           action={action}
+          display={display}
           table={{
             title: "Responses",
             columns: [{ key: "name", label: "Name" }],
@@ -49,13 +59,18 @@ async function renderWidget(action: { label: string; href: string }) {
 }
 
 describe("DataTableWidget", () => {
+  beforeEach(() => {
+    vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+  });
+
   afterEach(() => {
     for (const root of roots.splice(0)) {
-      root.unmount();
+      act(() => root.unmount());
     }
     document.body.innerHTML = "";
     process.env.VITE_APP_BASE_PATH = initialBasePath;
     vi.mocked(downloadFile).mockClear();
+    vi.unstubAllGlobals();
   });
 
   it("does not render executable action URLs", async () => {
@@ -99,6 +114,25 @@ describe("DataTableWidget", () => {
     ).toBeNull();
   });
 
+  it("renders table source chips and overflow actions from display metadata", async () => {
+    const container = await renderWidget(
+      { label: "Open responses", href: "/forms/form-1" },
+      {
+        sources: [{ label: "Responses", href: "/sources/responses" }],
+        actions: [{ type: "copy", label: "Copy query", text: "select 1" }],
+      },
+    );
+
+    expect(
+      container.querySelector('button[aria-label="Table actions"]'),
+    ).not.toBeNull();
+    expect(
+      Array.from(container.querySelectorAll("a")).some((link) =>
+        link.textContent?.includes("Responses"),
+      ),
+    ).toBe(true);
+  });
+
   it("exports visible table rows from the visible CSV download", async () => {
     const container = document.createElement("div");
     document.body.appendChild(container);