@artooi/ag-ui-web-component 0.10.0 → 0.12.0

package/src/ui/approval_card.ts

@@ -0,0 +1,119 @@
+import { DEFAULT_UI_STRINGS, type UiStrings } from "./ui_strings.js";
+
+/** What the inline approval card displays for one server-side-tool interrupt. */
+export interface ApprovalRequest {
+  /**
+   * Human-readable prompt from the AG-UI interrupt (e.g.
+   * `Approve delete_thing({…})?`). Falls back to the generic
+   * {@link UiStrings.approvalPrompt} when the interrupt carries no message.
+   */
+  message?: string;
+  /** Tool name, surfaced as a `data-tool-name` attribute for styling/tests. */
+  toolName?: string;
+}
+
+/** Build a labelled action button. */
+function actionButton(modifier: string, label: string): HTMLButtonElement {
+  const button = document.createElement("button");
+  button.type = "button";
+  button.className = `approval-btn approval-btn--${modifier}`;
+  button.setAttribute("part", `approval-button approval-${modifier}`);
+  button.textContent = label;
+  return button;
+}
+
+/** Options for {@link requestApproval}. */
+export interface ApprovalOptions {
+  /**
+   * Aborting this signal resolves the card as **denied** (buttons disabled,
+   * `data-resolved="denied"`) — the hook a Stop control uses to dismiss a
+   * pending approval when the user cancels the whole run.
+   */
+  signal?: AbortSignal;
+  /** Localized strings; defaults to the English {@link DEFAULT_UI_STRINGS}. */
+  strings?: UiStrings;
+}
+
+/**
+ * A fully custom renderer for a server-side-tool approval, set via
+ * `AgUiChat.approvalRenderer`. Receives the {@link ApprovalRequest} (the
+ * interrupt's message + tool name) and an `AbortSignal` that fires when the run
+ * is stopped, and resolves `true` to approve or `false` to deny. When provided
+ * it **replaces** the built-in {@link requestApproval} card entirely — the host
+ * owns the DOM, so it can render a native modal, a framework component, or
+ * anything else. See the `strings` / `::part()` seams for styling the built-in
+ * card instead of replacing it.
+ */
+export type ApprovalRenderer = (
+  request: ApprovalRequest,
+  options: { signal: AbortSignal },
+) => Promise<boolean>;
+
+/**
+ * Append an inline **approval** card to ``host`` and resolve when the user
+ * decides whether a gated *server-side* tool may run.
+ *
+ * The server-side approval gate is distinct from the client-tool confirmation
+ * card ({@link requestConfirmation}): a destructive server tool defers instead
+ * of executing, and the run finishes on an AG-UI *interrupt* the client answers
+ * with `resume[]`. This card is the browser half of that loop — it reads
+ * naturally after the tool-call card whose execution it gates, and resolves
+ * ``true`` to approve (run the tool) or ``false`` to deny. The card stays in the
+ * transcript as a resolved record (buttons disabled, `data-resolved` set)
+ * rather than vanishing.
+ */
+export function requestApproval(
+  host: Node & ParentNode,
+  request: ApprovalRequest,
+  options: ApprovalOptions = {},
+): Promise<boolean> {
+  const strings = options.strings ?? DEFAULT_UI_STRINGS;
+  return new Promise<boolean>((resolve) => {
+    const card = document.createElement("div");
+    card.className = "approval";
+    card.setAttribute("part", "approval");
+    if (request.toolName !== undefined) {
+      card.setAttribute("data-tool-name", request.toolName);
+    }
+    card.setAttribute("role", "group");
+    card.setAttribute("aria-label", strings.approveAction);
+
+    const body = document.createElement("div");
+    body.className = "approval-body";
+    body.setAttribute("part", "approval-body");
+    body.textContent = request.message ?? strings.approvalPrompt;
+
+    const actions = document.createElement("div");
+    actions.className = "approval-actions";
+    actions.setAttribute("part", "approval-actions");
+
+    const deny = actionButton("deny", strings.deny);
+    const approve = actionButton("approve", strings.approve);
+
+    let settled = false;
+    const close = (approved: boolean): void => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      deny.disabled = true;
+      approve.disabled = true;
+      card.setAttribute("data-resolved", approved ? "approved" : "denied");
+      resolve(approved);
+    };
+
+    deny.addEventListener("click", () => close(false));
+    approve.addEventListener("click", () => close(true));
+    options.signal?.addEventListener("abort", () => close(false), { once: true });
+
+    actions.append(deny, approve);
+    card.append(body, actions);
+    host.appendChild(card);
+    if (options.signal?.aborted === true) {
+      // The run was cancelled before the card could ask; record the denial.
+      close(false);
+      return;
+    }
+    approve.focus();
+  });
+}

package/src/ui/attachment_chips.ts

@@ -9,6 +9,7 @@ import type { AttachmentRef } from "../core/attachment.js";
 export function renderAttachmentChips(refs: readonly AttachmentRef[]): HTMLDivElement {
   const list = document.createElement("div");
   list.className = "attachment-chips";
+  list.setAttribute("part", "attachment-chips");
   for (const ref of refs) {
     list.appendChild(renderChip(ref));
   }
@@ -18,19 +19,23 @@ export function renderAttachmentChips(refs: readonly AttachmentRef[]): HTMLDivEl
 function renderChip(ref: AttachmentRef): HTMLDivElement {
   const chip = document.createElement("div");
   chip.className = "attachment-chip attachment-chip--ready";
+  chip.setAttribute("part", "attachment-chip");
 
   const icon = document.createElement("span");
   icon.className = "attachment-chip-icon";
+  icon.setAttribute("part", "attachment-chip-icon");
   icon.textContent = iconFor(ref.mime);
   icon.setAttribute("aria-hidden", "true");
 
   const name = document.createElement("span");
   name.className = "attachment-chip-name";
+  name.setAttribute("part", "attachment-chip-name");
   name.textContent = ref.name;
   name.title = ref.name;
 
   const size = document.createElement("span");
   size.className = "attachment-chip-size";
+  size.setAttribute("part", "attachment-chip-size");
   size.textContent = formatBytes(ref.size);
 
   chip.append(icon, name, size);

package/src/ui/attachment_tray.ts

@@ -205,19 +205,23 @@ export class AttachmentTray {
   #renderChip(item: TrayItem): HTMLDivElement {
     const chip = document.createElement("div");
     chip.className = `attachment-chip attachment-chip--${item.status}`;
+    chip.setAttribute("part", "attachment-chip");
 
     const icon = document.createElement("span");
     icon.className = "attachment-chip-icon";
+    icon.setAttribute("part", "attachment-chip-icon");
     icon.textContent = iconFor(item.file.type);
     icon.setAttribute("aria-hidden", "true");
 
     const name = document.createElement("span");
     name.className = "attachment-chip-name";
+    name.setAttribute("part", "attachment-chip-name");
     name.textContent = item.file.name;
     name.title = item.file.name;
 
     const meta = document.createElement("span");
     meta.className = "attachment-chip-size";
+    meta.setAttribute("part", "attachment-chip-size");
     meta.textContent =
       item.status === ATTACHMENT_STATUS.ERROR ? item.error : formatBytes(item.file.size);
 
@@ -226,8 +230,10 @@ export class AttachmentTray {
     if (item.status === ATTACHMENT_STATUS.UPLOADING) {
       const bar = document.createElement("div");
       bar.className = "attachment-chip-bar";
+      bar.setAttribute("part", "attachment-chip-bar");
       const fill = document.createElement("div");
       fill.className = "attachment-chip-bar-fill";
+      fill.setAttribute("part", "attachment-chip-bar-fill");
       fill.style.width = `${Math.round(item.progress * 100)}%`;
       bar.appendChild(fill);
       chip.appendChild(bar);
@@ -237,6 +243,7 @@ export class AttachmentTray {
       const retry = document.createElement("button");
       retry.type = "button";
       retry.className = "attachment-chip-retry";
+      retry.setAttribute("part", "attachment-chip-retry");
       retry.title = this.#strings.retry;
       retry.setAttribute("aria-label", this.#strings.retryUpload);
       retry.textContent = "↻";
@@ -247,6 +254,7 @@ export class AttachmentTray {
     const remove = document.createElement("button");
     remove.type = "button";
     remove.className = "attachment-chip-remove";
+    remove.setAttribute("part", "attachment-chip-remove");
     remove.title = this.#strings.remove;
     remove.setAttribute("aria-label", this.#strings.removeAttachment);
     remove.textContent = "✕";

package/src/ui/checkpoint_menu.ts

@@ -0,0 +1,153 @@
+import type { RunRow } from "../core/run_index.js";
+import { relativeTime } from "./relative_time.js";
+import { DEFAULT_UI_STRINGS, type UiStrings } from "./ui_strings.js";
+
+/** How the host continues a picked run. */
+export type CheckpointVerb = "resume" | "fork";
+
+/**
+ * The checkpoint panel: continuable runs, each offering **resume** or **fork**.
+ *
+ * A separate surface from the thread drawer on purpose — they are different
+ * axes. A thread is a conversation you switch *to*; a checkpoint is a run you
+ * continue *from*, and one thread can hold many. Folding them into one list
+ * would make "resume" look like "open", which it isn't: resuming starts a new
+ * run seeded from a snapshot.
+ *
+ * Only rows the server marked `continuable` are worth offering, so the host
+ * feeds those; a run with no snapshot would resume from nothing. Pure DOM in
+ * the spirit of {@link SkillsMenu} — the host appends {@link element}, toggles
+ * it, feeds rows via {@link setRuns}, and acts on {@link onPick}.
+ */
+export class CheckpointMenu {
+  /** The panel root. Append to the chat shell; hidden until opened. */
+  readonly element: HTMLDivElement;
+
+  readonly #onPick: (runId: string, verb: CheckpointVerb) => void;
+  readonly #list: HTMLDivElement;
+  readonly #heading: HTMLSpanElement;
+  #strings: UiStrings;
+  #runs: readonly RunRow[] = [];
+
+  constructor(
+    onPick: (runId: string, verb: CheckpointVerb) => void,
+    strings: UiStrings = DEFAULT_UI_STRINGS,
+  ) {
+    this.#onPick = onPick;
+    this.#strings = strings;
+
+    this.element = document.createElement("div");
+    this.element.className = "checkpoints";
+    this.element.setAttribute("part", "checkpoints");
+    this.element.setAttribute("role", "dialog");
+    this.element.setAttribute("aria-label", strings.checkpoints);
+    this.element.hidden = true;
+
+    const header = document.createElement("div");
+    header.className = "checkpoints-header";
+    header.setAttribute("part", "checkpoints-header");
+    this.#heading = document.createElement("span");
+    this.#heading.className = "checkpoints-title";
+    this.#heading.textContent = strings.checkpoints;
+    header.append(this.#heading);
+
+    this.#list = document.createElement("div");
+    this.#list.className = "checkpoints-list";
+    this.#list.setAttribute("part", "checkpoints-list");
+
+    this.element.append(header, this.#list);
+    this.element.addEventListener("keydown", (event) => {
+      if (event.key === "Escape") {
+        event.stopPropagation();
+        this.close();
+      }
+    });
+  }
+
+  /** Replace the rows. The host passes only `continuable` runs. */
+  setRuns(runs: readonly RunRow[]): void {
+    this.#runs = runs;
+    this.#render();
+  }
+
+  /** Re-localize a panel built before the host's strings resolved. */
+  setStrings(strings: UiStrings): void {
+    this.#strings = strings;
+    this.element.setAttribute("aria-label", strings.checkpoints);
+    this.#heading.textContent = strings.checkpoints;
+    this.#render();
+  }
+
+  open(): void {
+    this.element.hidden = false;
+  }
+
+  close(): void {
+    this.element.hidden = true;
+  }
+
+  get open_(): boolean {
+    return !this.element.hidden;
+  }
+
+  #render(): void {
+    this.#list.replaceChildren();
+    if (this.#runs.length === 0) {
+      const empty = document.createElement("div");
+      empty.className = "checkpoints-empty";
+      empty.setAttribute("part", "checkpoints-empty");
+      empty.textContent = this.#strings.noCheckpoints;
+      this.#list.append(empty);
+      return;
+    }
+    for (const run of this.#runs) {
+      this.#list.append(this.#row(run));
+    }
+  }
+
+  #row(run: RunRow): HTMLDivElement {
+    const row = document.createElement("div");
+    row.className = "checkpoint-row";
+    row.setAttribute("part", "checkpoint-row");
+
+    const label = document.createElement("span");
+    label.className = "checkpoint-label";
+    // A run id is opaque to a person, so the time is the identifying detail;
+    // the id rides `title` for anyone who needs to correlate with server logs.
+    label.textContent =
+      run.started_at === null
+        ? run.run_id
+        : relativeTime(Date.parse(run.started_at), Date.now(), this.#strings);
+    label.title = run.run_id;
+    row.append(label);
+
+    if (run.parent_run_id !== null) {
+      // Lineage, so a branch doesn't read as a duplicate of its parent.
+      const branch = document.createElement("span");
+      branch.className = "checkpoint-branch";
+      branch.setAttribute("part", "checkpoint-branch");
+      branch.textContent = this.#strings.forkedRun;
+      branch.title = run.parent_run_id;
+      row.append(branch);
+    }
+
+    row.append(
+      this.#action(run.run_id, "resume", this.#strings.resumeRun),
+      this.#action(run.run_id, "fork", this.#strings.forkRun),
+    );
+    return row;
+  }
+
+  #action(runId: string, verb: CheckpointVerb, label: string): HTMLButtonElement {
+    const button = document.createElement("button");
+    button.type = "button";
+    button.className = `checkpoint-action checkpoint-${verb}`;
+    button.setAttribute("part", `checkpoint-action checkpoint-${verb}`);
+    button.textContent = label;
+    button.addEventListener("click", () => {
+      this.close();
+      this.#onPick(runId, verb);
+    });
+    return button;
+  }
+}

package/src/ui/question_card.ts

@@ -0,0 +1,216 @@
+import { DEFAULT_UI_STRINGS, type UiStrings } from "./ui_strings.js";
+
+/** What the inline question card asks (the `ask_user` frontend tool's args). */
+export interface QuestionRequest {
+  /** The question shown to the user. */
+  question: string;
+  /**
+   * Preset choices rendered as radios. When empty/omitted the card is a plain
+   * free-text prompt.
+   */
+  options?: readonly string[];
+  /**
+   * Whether the user may type a custom answer. With `options`, adds an "other"
+   * radio revealing a text field; without options the card is free-text anyway.
+   */
+  allowCustom?: boolean;
+}
+
+/** Options for {@link requestQuestion}. */
+export interface QuestionOptions {
+  /**
+   * Aborting this signal resolves the card with an empty answer (fields
+   * disabled) — the hook a Stop control uses to dismiss an open question when
+   * the user cancels the whole run.
+   */
+  signal?: AbortSignal;
+  /** Localized strings; defaults to the English {@link DEFAULT_UI_STRINGS}. */
+  strings?: UiStrings;
+}
+
+/**
+ * A fully custom renderer for the `ask_user` question, set via
+ * `AgUiChat.askUserRenderer`. Receives the parsed {@link QuestionRequest} and an
+ * `AbortSignal` that fires when the run is stopped, and resolves with the user's
+ * answer (an empty string signals "no answer", e.g. on abort). When provided it
+ * **replaces** the built-in {@link requestQuestion} card entirely — the host owns
+ * the DOM, so it can render a native modal, a framework component, or anything
+ * else. See the `strings` / `::part()` seams for styling the built-in card
+ * instead of replacing it.
+ */
+export type QuestionRenderer = (
+  request: QuestionRequest,
+  options: { signal: AbortSignal },
+) => Promise<string>;
+
+/** A single custom-answer text field. */
+function answerInput(placeholder: string): HTMLInputElement {
+  const input = document.createElement("input");
+  input.type = "text";
+  input.className = "question-input";
+  input.setAttribute("part", "question-input");
+  input.placeholder = placeholder;
+  return input;
+}
+
+/**
+ * Append an inline **question** card to ``host`` and resolve with the user's
+ * answer — the browser half of the built-in `ask_user` frontend tool.
+ *
+ * Unlike the confirmation/approval cards (which resolve a yes/no), this collects
+ * a typed answer: a radio pick from ``options``, or free text (when
+ * ``allowCustom`` or no ``options`` are given). The card stays in the transcript
+ * as a resolved record (controls disabled, `data-resolved` set) rather than
+ * vanishing. A Stop while it is open resolves it with an empty string.
+ */
+export function requestQuestion(
+  host: Node & ParentNode,
+  request: QuestionRequest,
+  options: QuestionOptions = {},
+): Promise<string> {
+  const strings = options.strings ?? DEFAULT_UI_STRINGS;
+  const choices = request.options ?? [];
+  const hasChoices = choices.length > 0;
+  // Free text is offered when there are no preset choices, or when custom
+  // answers are explicitly allowed alongside them (via an "other" radio).
+  const allowsText = !hasChoices || request.allowCustom === true;
+
+  return new Promise<string>((resolve) => {
+    const card = document.createElement("div");
+    card.className = "question";
+    card.setAttribute("part", "question");
+    card.setAttribute("role", "group");
+    card.setAttribute("aria-label", strings.askUserAction);
+
+    const body = document.createElement("div");
+    body.className = "question-body";
+    body.setAttribute("part", "question-body");
+    body.textContent = request.question;
+
+    const form = document.createElement("div");
+    form.className = "question-options";
+    form.setAttribute("part", "question-options");
+
+    // `name` scopes the radio group to this card so multiple open cards don't
+    // interfere; a per-card token keeps it unique without module state.
+    const group = `q-${choices.length}-${request.question.length}`;
+    const radios: HTMLInputElement[] = [];
+    for (const choice of choices) {
+      const label = document.createElement("label");
+      label.className = "question-choice";
+      label.setAttribute("part", "question-choice");
+      const radio = document.createElement("input");
+      radio.type = "radio";
+      radio.name = group;
+      radio.value = choice;
+      radio.setAttribute("part", "question-radio");
+      const text = document.createElement("span");
+      text.setAttribute("part", "question-choice-text");
+      text.textContent = choice;
+      label.append(radio, text);
+      form.appendChild(label);
+      radios.push(radio);
+    }
+
+    // The "other" radio (only alongside choices) toggles the free-text field.
+    let otherRadio: HTMLInputElement | null = null;
+    let input: HTMLInputElement | null = null;
+    if (allowsText) {
+      input = answerInput(strings.answerPlaceholder);
+      if (hasChoices) {
+        const label = document.createElement("label");
+        label.className = "question-choice";
+        label.setAttribute("part", "question-choice");
+        otherRadio = document.createElement("input");
+        otherRadio.type = "radio";
+        otherRadio.name = group;
+        otherRadio.value = "";
+        otherRadio.setAttribute("part", "question-radio");
+        const text = document.createElement("span");
+        text.setAttribute("part", "question-choice-text");
+        text.textContent = strings.otherOption;
+        label.append(otherRadio, text);
+        form.appendChild(label);
+        input.disabled = true;
+      }
+      form.appendChild(input);
+    }
+
+    const actions = document.createElement("div");
+    actions.className = "question-actions";
+    actions.setAttribute("part", "question-actions");
+    const submit = document.createElement("button");
+    submit.type = "button";
+    submit.className = "question-btn";
+    submit.setAttribute("part", "question-button");
+    submit.textContent = strings.submit;
+    actions.appendChild(submit);
+
+    let settled = false;
+    const answerFor = (): string | null => {
+      const picked = radios.find((r) => r.checked);
+      if (picked !== undefined) {
+        return picked.value;
+      }
+      if (input !== null && (otherRadio === null || otherRadio.checked)) {
+        const typed = input.value.trim();
+        return typed === "" ? null : typed;
+      }
+      return null;
+    };
+    const refresh = (): void => {
+      if (input !== null && otherRadio !== null) {
+        input.disabled = !otherRadio.checked;
+      }
+      submit.disabled = answerFor() === null;
+    };
+    const close = (answer: string): void => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      submit.disabled = true;
+      for (const radio of radios) {
+        radio.disabled = true;
+      }
+      if (otherRadio !== null) {
+        otherRadio.disabled = true;
+      }
+      if (input !== null) {
+        input.disabled = true;
+      }
+      card.setAttribute("data-resolved", answer === "" ? "cancelled" : "answered");
+      resolve(answer);
+    };
+
+    for (const radio of [...radios, ...(otherRadio !== null ? [otherRadio] : [])]) {
+      radio.addEventListener("change", refresh);
+    }
+    input?.addEventListener("input", refresh);
+    input?.addEventListener("keydown", (event) => {
+      if (event.key === "Enter") {
+        event.preventDefault();
+        const answer = answerFor();
+        if (answer !== null) {
+          close(answer);
+        }
+      }
+    });
+    submit.addEventListener("click", () => {
+      const answer = answerFor();
+      if (answer !== null) {
+        close(answer);
+      }
+    });
+    options.signal?.addEventListener("abort", () => close(""), { once: true });
+
+    card.append(body, form, actions);
+    host.appendChild(card);
+    if (options.signal?.aborted === true) {
+      close("");
+      return;
+    }
+    refresh();
+    (hasChoices ? radios[0] : input)?.focus();
+  });
+}

package/src/ui/skills_menu.ts

@@ -24,9 +24,11 @@ export class SkillsMenu {
     this.#onPick = onPick;
     this.chips = document.createElement("div");
     this.chips.className = "skill-chips";
+    this.chips.setAttribute("part", "skill-chips");
     this.chips.hidden = true;
     this.palette = document.createElement("div");
     this.palette.className = "skill-palette";
+    this.palette.setAttribute("part", "skill-palette");
     this.palette.setAttribute("role", "listbox");
     this.palette.hidden = true;
   }
@@ -137,6 +139,7 @@ export class SkillsMenu {
       const button = document.createElement("button");
       button.type = "button";
       button.className = "skill-chip";
+      button.setAttribute("part", "skill-chip");
       button.textContent = skill.title;
       button.addEventListener("click", () => this.#pick(skill));
       this.chips.appendChild(button);
@@ -149,17 +152,20 @@ export class SkillsMenu {
       const item = document.createElement("button");
       item.type = "button";
       item.className = "skill-item";
+      item.setAttribute("part", "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.setAttribute("part", "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.setAttribute("part", "skill-item-desc");
         desc.textContent = skill.description;
         item.appendChild(desc);
       }