@artooi/ag-ui-web-component 0.1.0 → 0.2.0

package/src/tools/route_map.ts

@@ -0,0 +1,140 @@
+import { X_NAVIGATES_KEY } from "../constants.js";
+import type { ClientTool } from "./client_tool_registry.js";
+
+/** A single navigable route the host declares for the agent. */
+export interface Route {
+  /** Stable id the agent uses with `navigate_to_route`. */
+  readonly id: string;
+  /**
+   * The URL path to navigate to. May contain `:name` placeholders for dynamic
+   * segments (e.g. `/admin/shop/book/:pk/change/`); the agent fills them via
+   * the `navigate_to_route` `params` argument. Real apps are mostly
+   * parameterised — few pages have a truly static path.
+   */
+  readonly path: string;
+  /** Human label shown to the agent. */
+  readonly title?: string;
+  /** Optional grouping (e.g. an app or section). */
+  readonly group?: string;
+  /** Optional longer description of when to use the route. */
+  readonly description?: string;
+}
+
+/** The host-declared catalog of navigable routes. */
+export type RouteMap = readonly Route[];
+
+/** A route enriched with its derived dynamic-segment parameter names. */
+export interface RouteWithParams extends Route {
+  /** Names of the `:name` placeholders in {@link Route.path} (may be empty). */
+  readonly pathParams: readonly string[];
+}
+
+const PATH_PARAM_RE = /:([A-Za-z_][A-Za-z0-9_]*)/g;
+
+/** The `:name` path-parameter names declared in a path template, in order. */
+function pathParamNames(path: string): string[] {
+  const names: string[] = [];
+  for (const match of path.matchAll(PATH_PARAM_RE)) {
+    const name = match[1];
+    if (name !== undefined) {
+      names.push(name);
+    }
+  }
+  return names;
+}
+
+/**
+ * Substitute `:name` placeholders in ``path`` from ``params``.
+ *
+ * Returns the concrete path plus the params *not* consumed by a placeholder, so
+ * the caller can append those as a query string. Throws (referencing
+ * ``routeId``) when a declared path param is missing or empty — a half-filled
+ * path must never be navigated to.
+ */
+function fillPath(
+  routeId: string,
+  path: string,
+  params: Record<string, unknown>,
+): { path: string; leftover: Record<string, unknown> } {
+  const leftover: Record<string, unknown> = { ...params };
+  const filled = path.replace(PATH_PARAM_RE, (_match, name: string) => {
+    const value = params[name];
+    if (value === undefined || value === null || String(value) === "") {
+      throw new Error(`route "${routeId}" requires path param "${name}"`);
+    }
+    delete leftover[name];
+    return encodeURIComponent(String(value));
+  });
+  return { path: filled, leftover };
+}
+
+/** Append `params` to `path` as a query string (no-op when empty). */
+function withQuery(path: string, params: Record<string, unknown>): string {
+  const usp = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    usp.set(key, String(value));
+  }
+  const query = usp.toString();
+  return query === "" ? path : `${path}?${query}`;
+}
+
+/**
+ * The built-in `route.*` tools, bound to live getters so a host can set
+ * `routeMap` / `navigate` before or after mount.
+ *
+ * `list_routes` is read-only and advertises each route's dynamic
+ * `pathParams` so the model knows what to supply. `navigate_to_route` is marked
+ * `x-navigates` so an MPA reload checkpoints + resumes; it substitutes path
+ * params into the template and appends any remaining params as a query string.
+ * When the host supplies a `navigate(path)` callback (an SPA), the element
+ * routes client-side instead and the run loop simply continues — see
+ * `AgUiChat`'s execute path.
+ */
+export function createRouteTools(
+  getRouteMap: () => RouteMap,
+  getNavigate: () => ((path: string) => void) | null,
+): ClientTool[] {
+  return [
+    {
+      name: "list_routes",
+      description:
+        "List the routes the app can navigate to. Each route's `pathParams` " +
+        "names the dynamic segments to pass as `params` to `navigate_to_route`.",
+      parameters: { type: "object", properties: {}, required: [] },
+      handler: (): RouteWithParams[] =>
+        getRouteMap().map((route) => ({ ...route, pathParams: pathParamNames(route.path) })),
+    },
+    {
+      name: "navigate_to_route",
+      description:
+        "Navigate to one of the app's routes by its id, filling any dynamic " +
+        "`:name` path segments (and extra query params) from `params`.",
+      parameters: {
+        type: "object",
+        properties: {
+          route_id: { type: "string" },
+          params: { type: "object" },
+        },
+        required: ["route_id"],
+        [X_NAVIGATES_KEY]: true,
+      },
+      handler: (args) => {
+        const routeId = args["route_id"];
+        const route = getRouteMap().find((r) => r.id === routeId);
+        if (route === undefined) {
+          throw new Error(`unknown route "${String(routeId)}"`);
+        }
+        const provided = (args["params"] as Record<string, unknown> | undefined) ?? {};
+        const { path: filledPath, leftover } = fillPath(route.id, route.path, provided);
+        const path = withQuery(filledPath, leftover);
+        const navigate = getNavigate();
+        if (navigate !== null) {
+          navigate(path);
+        } else {
+          window.location.assign(path);
+        }
+        return { navigated: true, path };
+      },
+    },
+  ];
+}

package/src/{state_hook.ts → tools/state_hook.ts}

@@ -1,5 +1,5 @@
+import { X_DESTRUCTIVE_KEY } from "../constants.js";
 import type { ClientTool } from "./client_tool_registry.js";
-import { X_DESTRUCTIVE_KEY } from "./constants.js";
 
 /**
  * A binding from a named piece of host application state to agent tools.

package/src/ui/confirmation_card.ts

@@ -0,0 +1,71 @@
+/** What the inline confirmation card displays. */
+export interface ConfirmationRequest {
+  toolName: string;
+  args: Record<string, unknown>;
+  /**
+   * Human-readable prompt (from the tool's `x-confirm` metadata), e.g.
+   * "Activate this project?". Falls back to a generic `Run "<tool>"?`.
+   */
+  message?: string;
+}
+
+/** Build a labelled action button. */
+function actionButton(modifier: string, label: string): HTMLButtonElement {
+  const button = document.createElement("button");
+  button.type = "button";
+  button.className = `confirm-btn confirm-btn--${modifier}`;
+  button.textContent = label;
+  return button;
+}
+
+/**
+ * Append an inline confirmation card to ``host`` (the chat message list) and
+ * resolve when the user decides.
+ *
+ * Unlike a modal overlay, the card lives in the transcript right where the
+ * action is — it reads naturally after the assistant's explanation and never
+ * steals focus from the page. Resolves ``true`` on confirm, ``false`` on
+ * cancel. The card stays in the transcript as a resolved record (buttons
+ * disabled, `data-resolved` set) rather than vanishing.
+ */
+export function requestConfirmation(
+  host: Node & ParentNode,
+  request: ConfirmationRequest,
+): Promise<boolean> {
+  return new Promise<boolean>((resolve) => {
+    const card = document.createElement("div");
+    card.className = "confirm";
+    card.setAttribute("data-tool-name", request.toolName);
+    card.setAttribute("role", "group");
+    card.setAttribute("aria-label", "Confirm action");
+
+    const body = document.createElement("div");
+    body.className = "confirm-body";
+    body.textContent = request.message ?? `Run “${request.toolName}”?`;
+
+    const args = document.createElement("pre");
+    args.className = "confirm-args";
+    args.textContent = JSON.stringify(request.args, null, 2);
+
+    const actions = document.createElement("div");
+    actions.className = "confirm-actions";
+
+    const cancel = actionButton("cancel", "Cancel");
+    const confirm = actionButton("confirm", "Confirm");
+
+    const close = (accepted: boolean): void => {
+      cancel.disabled = true;
+      confirm.disabled = true;
+      card.setAttribute("data-resolved", accepted ? "confirmed" : "declined");
+      resolve(accepted);
+    };
+
+    cancel.addEventListener("click", () => close(false));
+    confirm.addEventListener("click", () => close(true));
+
+    actions.append(cancel, confirm);
+    card.append(body, args, actions);
+    host.appendChild(card);
+    confirm.focus();
+  });
+}

package/src/ui/render_markdown.ts

@@ -0,0 +1,68 @@
+import DOMPurify from "dompurify";
+import { marked } from "marked";
+
+// GitHub-flavoured markdown with single-newline line breaks (chat-like).
+marked.setOptions({ gfm: true, breaks: true });
+
+// Conservative allowlist for assistant chat content: inline emphasis, code,
+// lists, quotes, headings, links, tables, and images. Deliberately excludes
+// `iframe`, `style`, and any scripting — rendering untrusted model/tool output
+// as HTML is an XSS surface, so the sanitiser is the load-bearing safety net.
+const ALLOWED_TAGS = [
+  "a",
+  "p",
+  "br",
+  "strong",
+  "em",
+  "b",
+  "i",
+  "u",
+  "s",
+  "del",
+  "code",
+  "pre",
+  "ul",
+  "ol",
+  "li",
+  "blockquote",
+  "h1",
+  "h2",
+  "h3",
+  "h4",
+  "h5",
+  "h6",
+  "hr",
+  "span",
+  "table",
+  "thead",
+  "tbody",
+  "tr",
+  "th",
+  "td",
+  "img",
+];
+
+const ALLOWED_ATTR = ["href", "title", "class", "src", "alt", "width", "height"];
+
+/**
+ * Render markdown (and any embedded raw HTML) to a sanitised HTML string.
+ *
+ * Both markdown syntax and literal HTML flow through one path: `marked` emits
+ * HTML, then DOMPurify strips everything outside {@link ALLOWED_TAGS} /
+ * {@link ALLOWED_ATTR} (scripts, event handlers, `javascript:` URLs, etc.).
+ * Links are hardened with `target="_blank"` + `rel="noopener noreferrer"`.
+ *
+ * The result is trimmed so a single-paragraph message round-trips to clean
+ * `textContent` (no trailing newline from the wrapping `<p>`).
+ */
+export function renderMarkdown(text: string): string {
+  const rendered = marked.parse(text, { async: false });
+  const clean = DOMPurify.sanitize(rendered, { ALLOWED_TAGS, ALLOWED_ATTR });
+  const template = document.createElement("template");
+  template.innerHTML = clean;
+  for (const anchor of template.content.querySelectorAll("a[href]")) {
+    anchor.setAttribute("target", "_blank");
+    anchor.setAttribute("rel", "noopener noreferrer");
+  }
+  return template.innerHTML.trim();
+}

package/src/ui/reveal_words.ts

@@ -0,0 +1,41 @@
+/** Collect the text nodes under ``root`` with their parents (depth-first). */
+function collectTextNodes(root: Node, out: { node: Text; parent: Node }[]): void {
+  for (const child of Array.from(root.childNodes)) {
+    if (child.nodeType === Node.TEXT_NODE) {
+      out.push({ node: child as Text, parent: root });
+    } else {
+      collectTextNodes(child, out);
+    }
+  }
+}
+
+/**
+ * Wrap each word under ``root`` in `<span class="word" style="--ag-ui-word-index: N">`
+ * so CSS can reveal them one-by-one (staggered by the index). Whitespace is
+ * preserved as plain text. Used for the `word` text-animation mode on a
+ * completed assistant message; pure DOM, idempotent enough to re-run.
+ */
+export function wrapWords(root: HTMLElement): void {
+  const texts: { node: Text; parent: Node }[] = [];
+  collectTextNodes(root, texts);
+  let index = 0;
+  for (const { node, parent } of texts) {
+    const fragment = document.createDocumentFragment();
+    for (const part of node.data.split(/(\s+)/)) {
+      if (part === "") {
+        continue;
+      }
+      if (/\s/.test(part)) {
+        fragment.appendChild(document.createTextNode(part));
+        continue;
+      }
+      const span = document.createElement("span");
+      span.className = "word";
+      span.style.setProperty("--ag-ui-word-index", String(index));
+      span.textContent = part;
+      fragment.appendChild(span);
+      index += 1;
+    }
+    parent.replaceChild(fragment, node);
+  }
+}

package/src/ui/skills_menu.ts

@@ -0,0 +1,171 @@
+import type { Skill } from "../skills/skill.js";
+
+/**
+ * The two skill surfaces over a single catalog: a **chips** row (the
+ * `chip: true` subset) and a **`/`-command palette** (all skills, filtered).
+ * Both are opt-in. Pure DOM; the host ({@link AgUiChat}) appends
+ * {@link chips} + {@link palette}, feeds input via {@link onInput} /
+ * {@link onKeydown}, and acts on the {@link onPick} callback.
+ */
+export class SkillsMenu {
+  /** Chips row — append above the input. Hidden unless chips are enabled and present. */
+  readonly chips: HTMLDivElement;
+  /** The `/`-command dropdown — append in the input area. Hidden until opened. */
+  readonly palette: HTMLDivElement;
+
+  readonly #onPick: (skill: Skill) => void;
+  #skills: readonly Skill[] = [];
+  #chipsEnabled = false;
+  #slashEnabled = false;
+  #filtered: Skill[] = [];
+  #activeIndex = 0;
+
+  constructor(onPick: (skill: Skill) => void) {
+    this.#onPick = onPick;
+    this.chips = document.createElement("div");
+    this.chips.className = "skill-chips";
+    this.chips.hidden = true;
+    this.palette = document.createElement("div");
+    this.palette.className = "skill-palette";
+    this.palette.setAttribute("role", "listbox");
+    this.palette.hidden = true;
+  }
+
+  /** Replace the catalog (both surfaces re-derive from it). */
+  setSkills(skills: readonly Skill[]): void {
+    this.#skills = skills;
+    this.#renderChips();
+  }
+
+  enableChips(enabled: boolean): void {
+    this.#chipsEnabled = enabled;
+    this.#renderChips();
+  }
+
+  enableSlash(enabled: boolean): void {
+    this.#slashEnabled = enabled;
+  }
+
+  /** Whether the palette is currently open. */
+  isOpen(): boolean {
+    return !this.palette.hidden;
+  }
+
+  /**
+   * React to an input value change: open + filter the palette when slash mode
+   * is on and the value starts with `/`, otherwise close it.
+   */
+  onInput(value: string): void {
+    if (this.#slashEnabled && value.startsWith("/")) {
+      this.#open(value.slice(1));
+    } else {
+      this.close();
+    }
+  }
+
+  /**
+   * Handle a keydown while the palette is open. Returns ``true`` when consumed
+   * (the host should `preventDefault` and skip its own handling).
+   */
+  onKeydown(event: KeyboardEvent): boolean {
+    if (!this.isOpen()) {
+      return false;
+    }
+    if (event.key === "ArrowDown") {
+      this.#move(1);
+      return true;
+    }
+    if (event.key === "ArrowUp") {
+      this.#move(-1);
+      return true;
+    }
+    if (event.key === "Escape") {
+      this.close();
+      return true;
+    }
+    if (event.key === "Enter") {
+      // `slice(i, i+1)` yields a 0-or-1 element array; forEach gives a
+      // definite Skill (no indexed-access `| undefined`).
+      this.#filtered.slice(this.#activeIndex, this.#activeIndex + 1).forEach((skill) => {
+        this.#pick(skill);
+      });
+      return true;
+    }
+    return false;
+  }
+
+  /** Close the palette. */
+  close(): void {
+    this.palette.hidden = true;
+    this.palette.replaceChildren();
+  }
+
+  #open(query: string): void {
+    const needle = query.trim().toLowerCase();
+    const matches = this.#skills.filter(
+      (skill) =>
+        skill.name.toLowerCase().includes(needle) || skill.title.toLowerCase().includes(needle),
+    );
+    if (matches.length === 0) {
+      this.close();
+      return;
+    }
+    this.#filtered = matches;
+    this.#activeIndex = 0;
+    this.#renderPalette();
+    this.palette.hidden = false;
+  }
+
+  #move(delta: number): void {
+    const count = this.#filtered.length;
+    this.#activeIndex = (this.#activeIndex + delta + count) % count;
+    this.#renderPalette();
+  }
+
+  #pick(skill: Skill): void {
+    this.close();
+    this.#onPick(skill);
+  }
+
+  #renderChips(): void {
+    this.chips.replaceChildren();
+    const chipSkills = this.#chipsEnabled
+      ? this.#skills.filter((skill) => skill.chip === true)
+      : [];
+    this.chips.hidden = chipSkills.length === 0;
+    for (const skill of chipSkills) {
+      const button = document.createElement("button");
+      button.type = "button";
+      button.className = "skill-chip";
+      button.textContent = skill.title;
+      button.addEventListener("click", () => this.#pick(skill));
+      this.chips.appendChild(button);
+    }
+  }
+
+  #renderPalette(): void {
+    this.palette.replaceChildren();
+    this.#filtered.forEach((skill, index) => {
+      const item = document.createElement("button");
+      item.type = "button";
+      item.className = "skill-item";
+      item.setAttribute("role", "option");
+      item.setAttribute("aria-selected", index === this.#activeIndex ? "true" : "false");
+
+      const title = document.createElement("span");
+      title.className = "skill-item-title";
+      title.textContent = skill.title;
+      item.appendChild(title);
+
+      if (skill.description !== undefined) {
+        const desc = document.createElement("span");
+        desc.className = "skill-item-desc";
+        desc.textContent = skill.description;
+        item.appendChild(desc);
+      }
+
+      item.addEventListener("click", () => this.#pick(skill));
+      this.palette.appendChild(item);
+    });
+  }
+}