@artooi/ag-ui-web-component 0.25.2 → 0.26.0

package/src/ui/chart_spec_from.ts

@@ -0,0 +1,106 @@
+/**
+ * Narrow untrusted input into a {@link ChartSpec}.
+ *
+ * Both arrival routes are untrusted in the same way — a model writes one, a
+ * server the other — so neither is taken on shape. Kept out of the renderer
+ * because the renderer's job is drawing, and a value that reaches it has
+ * already been vouched for.
+ */
+
+import type { ChartKind, ChartSpec } from "./chart_block.js";
+
+const KINDS: readonly ChartKind[] = ["bar", "line", "pie", "scatter", "stacked"];
+
+/**
+ * Most points a spec may carry, across every series.
+ *
+ * Not a taste limit. `Math.max(0, ...values)` throws `RangeError` on a large
+ * enough spread, and the renderer runs inside the history replay, where a throw
+ * abandons the replay and takes every later turn of the transcript with it —
+ * permanently, on every reload. A chart nobody can read is a far smaller
+ * problem than a conversation that silently loses its tail.
+ */
+const MAX_POINTS = 20_000;
+
+/**
+ * Largest magnitude a point may carry.
+ *
+ * `Number.isFinite` is not enough on its own: two finite extremes still give an
+ * infinite *range*, and `(value - min) / Infinity` is `NaN`, which reaches the
+ * DOM as `y="NaN"`. Bounding the values bounds the range.
+ */
+const MAX_MAGNITUDE = 1e15;
+
+function asKind(value: unknown): ChartKind {
+  // Anything unrecognised falls back to `bar` rather than refusing the spec: an
+  // unknown kind is a caller reaching for a chart type we do not draw, and the
+  // data is still worth showing.
+  return KINDS.includes(value as ChartKind) ? (value as ChartKind) : "bar";
+}
+
+function asNumbers(value: unknown): number[] | null {
+  if (!Array.isArray(value)) {
+    return null;
+  }
+  const out: number[] = [];
+  for (const item of value) {
+    // `Number.isFinite` rather than `typeof === "number"`: JSON encoders render
+    // NaN and Infinity as nulls or strings depending on the encoder, and either
+    // would scale into a chart with no visible extent.
+    if (typeof item !== "number" || !Number.isFinite(item)) {
+      return null;
+    }
+    if (Math.abs(item) > MAX_MAGNITUDE) {
+      return null;
+    }
+    out.push(item);
+  }
+  return out;
+}
+
+function asStrings(value: unknown): string[] | null {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+    return null;
+  }
+  return value as string[];
+}
+
+/** A well-formed spec, or `null` for anything that cannot be drawn honestly. */
+export function chartSpecFrom(value: unknown): ChartSpec | null {
+  if (typeof value !== "object" || value === null) {
+    return null;
+  }
+  const raw = value as Record<string, unknown>;
+  const labels = asStrings(raw["labels"]);
+  if (labels === null || !Array.isArray(raw["series"])) {
+    return null;
+  }
+
+  const series: { label: string; points: number[] }[] = [];
+  for (const entry of raw["series"]) {
+    if (typeof entry !== "object" || entry === null) {
+      return null;
+    }
+    const item = entry as Record<string, unknown>;
+    const points = asNumbers(item["points"]);
+    // A series with a different number of points than there are labels would
+    // silently misalign every value after the gap. A chart that is subtly wrong
+    // still reads as authoritative, which is worse than no chart at all.
+    if (points === null || points.length !== labels.length) {
+      return null;
+    }
+    series.push({ label: typeof item["label"] === "string" ? item["label"] : "", points });
+  }
+  if (series.length === 0) {
+    return null;
+  }
+  if (series.length * labels.length > MAX_POINTS) {
+    return null;
+  }
+
+  const kind = asKind(raw["kind"]);
+  const title = raw["title"];
+  // The key is omitted rather than set to `undefined`: `title` is genuinely
+  // optional and this tsconfig distinguishes absent from present-and-undefined.
+  return typeof title === "string" ? { kind, title, labels, series } : { kind, labels, series };
+}

package/src/ui/chart_tool.ts

@@ -0,0 +1,64 @@
+/**
+ * The built-in `render_chart` tool: the agent-called route to a chart.
+ *
+ * A thin thing on purpose. It carries no `handler` of its own beyond reporting
+ * back to the model, because everything it does is drawing — which lives in
+ * `render`, the half the component replays. A consumer wanting charts gets this
+ * without writing a renderer; a consumer wanting something else writes their own
+ * tool against the same seam.
+ */
+
+import type { ClientTool } from "../tools/client_tool_registry.js";
+import { renderChart } from "./chart_block.js";
+import { chartSpecFrom } from "./chart_spec_from.js";
+
+/** The name the built-in chart tool registers under. */
+export const CHART_TOOL_NAME = "render_chart";
+
+function draw(args: Record<string, unknown>): HTMLDivElement | null {
+  const spec = chartSpecFrom(args);
+  return spec === null ? null : renderChart(spec);
+}
+
+const REJECTED =
+  "chart not rendered: expected labels (strings) and series, each with one finite number per label";
+
+/** The built-in chart tool. */
+export function createChartTool(): ClientTool {
+  return {
+    name: CHART_TOOL_NAME,
+    description:
+      "Show a chart in the conversation. Supply the data and the page draws it. " +
+      "Every series must have exactly one point per label.",
+    parameters: {
+      type: "object",
+      properties: {
+        kind: { type: "string", enum: ["bar", "line", "pie", "scatter", "stacked"] },
+        title: { type: "string" },
+        labels: { type: "array", items: { type: "string" } },
+        series: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              label: { type: "string" },
+              points: { type: "array", items: { type: "number" } },
+            },
+            required: ["points"],
+          },
+        },
+      },
+      required: ["labels", "series"],
+      "x-summary": "Draw a chart",
+    },
+    // Says what happened and nothing else; the drawing is `render`'s job. Told
+    // plainly when the arguments are unusable, because the model can fix that
+    // and retry — a silent no-op would leave it believing the chart is on screen.
+    // Answers on what was actually drawn, not on what validated. A spec can
+    // pass validation and still have nothing to show -- zero labels matches zero
+    // points -- and reporting success then would leave the model believing a
+    // chart is on screen.
+    handler: (args: Record<string, unknown>) => (draw(args) === null ? REJECTED : "chart rendered"),
+    render: draw,
+  };
+}

package/src/ui/styles.ts

@@ -1528,6 +1528,50 @@ export const STYLES = `
   margin-top: 6px;
 }
 
+/* Charts.
+ *
+ * The SVG scales to the column and carries no colours of its own beyond the
+ * series palette, so a host restyles it the same way it restyles everything
+ * else. Series colours are custom properties with fallbacks rather than fixed
+ * values, and the axis furniture inherits currentColor at low opacity so it
+ * reads correctly in either theme without a second palette.
+ */
+.chart-block {
+  align-self: stretch;
+  max-width: 100%;
+  margin: 6px 0;
+  color: var(--_fg);
+}
+
+.chart-title {
+  margin-bottom: 2px;
+  font-size: 0.85em;
+  font-weight: 600;
+  opacity: 0.85;
+}
+
+.chart-legend {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 4px 12px;
+  margin-top: 4px;
+  font-size: 0.78em;
+  opacity: 0.75;
+}
+
+.chart-legend-item {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+}
+
+.chart-legend-swatch {
+  width: 9px;
+  height: 9px;
+  border-radius: 2px;
+  flex: 0 0 auto;
+}
+
 .run-notice {
   display: inline-flex;
   align-items: center;

package/src/version.ts

@@ -1 +1 @@
-export const VERSION: string = "0.25.2";
+export const VERSION: string = "0.26.0";