@4djs/ai-widgets

Built-in assistant widgets for Data Explorer. Widgets are render-only: they receive a data envelope and paint UI. They never fetch from the datastore.

Hosts (e.g. Data Explorer) gather data with @datastore/query, shape an envelope, then call @widgets/render. Results render inline via WidgetRenderer.

Usage

import {
  WidgetRenderer,
  listBuiltinWidgets,
  listWidgetAiGuidance,
  getWidgetRenderPropsFromResult,
  buildWidgetRenderInputSchema,
  buildWidgetRenderToolDescription,
  parseWidgetRenderArgs,
} from "@4djs/ai-widgets";
import "@4djs/ai-widgets/styles.css";

Render a tool result

const props = getWidgetRenderPropsFromResult(step.result);
if (props) {
  return <WidgetRenderer {...props} mode={props.mode ?? "light"} />;
}

Host tool (data in)

Compose the tool description and JSON Schema from the registry so per-widget AI instructions stay next to each component (not in the app system prompt):

const opts = { disabledWidgetTypes };
const schema = buildWidgetRenderInputSchema(opts);
const description = buildWidgetRenderToolDescription(opts);
const parsed = parseWidgetRenderArgs(args, opts);
if (!parsed.ok) return toolResultErr(parsed.error);
return toolResultOk({
  widget: { title: parsed.value.title, data: parsed.value.data },
});

Each widget definition can declare:

{
  type: "pie",
  label: "Pie Chart",
  description: "Part-to-whole slices", // human UI
  example: { type: "pie", values: [{ label: "A", value: 3 }] },
  ai: {
    summary: "Part-to-whole distribution as a pie",
    dataShape: '{ "type": "pie", "values": [{ "label", "value" }] }',
    aliases: 'Also accepts series/data as [{ "key", "value" }]',
  },
  Render: …
}

Example tool args:

{
  "title": "Cars by category",
  "data": {
    "type": "pie",
    "values": [
      { "label": "SUV", "value": 12 },
      { "label": "Sedan", "value": 8 }
    ]
  }
}

Built-in types

KPI, line, area, bar, pie, donut, scatter, heatmap, table, gauge, progress, funnel, map, timeline, filter.

Scripts

bun run typecheck
bun run test
bun run lint

Profile enablement

Data Explorer stores disabledWidgetTypes per profile. The Widgets settings panel toggles types and refreshes the @widgets/render schema so disabled types are omitted from the model tool enum.