@artooi/ag-ui-web-component 0.27.0 → 0.29.0

package/src/ui/approval_card.ts

@@ -10,6 +10,11 @@ export interface ApprovalRequest {
   message?: string;
   /** Tool name, surfaced as a `data-tool-name` attribute for styling/tests. */
   toolName?: string;
+  /**
+   * The call's arguments, shown for editing when {@link ApprovalOptions.onEdit}
+   * is set. Omitted when the interrupt names no call whose arguments are known.
+   */
+  args?: Record<string, unknown>;
 }
 
 /** Build a labelled action button. */
@@ -31,6 +36,19 @@ export interface ApprovalOptions {
   signal?: AbortSignal;
   /** Localized strings; defaults to the English {@link DEFAULT_UI_STRINGS}. */
   strings?: UiStrings;
+  /**
+   * Offer the call's arguments for editing, and receive what the user approved.
+   *
+   * Called **only** on approval, and only when the text parses and differs from
+   * what was proposed -- an untouched call resolves as a plain approval, so a
+   * server sees `editedArgs` exactly when something was actually edited.
+   *
+   * Absent means no editor, which is deliberate: AG-UI gates this on the
+   * agent's own `approveWithEdits` capability, and a card that let a user
+   * rewrite arguments a server will discard is worse than one that does not
+   * offer to.
+   */
+  onEdit?: (args: Record<string, unknown>) => void;
 }
 
 /**
@@ -78,6 +96,8 @@ export function requestApproval(
     body.setAttribute("part", "approval-body");
     body.textContent = request.message ?? strings.approvalPrompt;
 
+    const editor = buildEditor(request, options, strings);
+
     const actions = document.createElement("div");
     actions.className = "approval-actions";
     actions.setAttribute("part", "approval-actions");
@@ -98,11 +118,19 @@ export function requestApproval(
     };
 
     deny.addEventListener("click", () => close(false));
-    approve.addEventListener("click", () => close(true));
+    approve.addEventListener("click", () => {
+      if (editor !== null && !editor.commit()) {
+        // Unparseable JSON: say so on the card and stay open. Approving what
+        // the user did not write -- the original arguments -- would be the one
+        // outcome they cannot see coming.
+        return;
+      }
+      close(true);
+    });
     options.signal?.addEventListener("abort", () => close(false), { once: true });
 
     actions.append(deny, approve);
-    card.append(body, actions);
+    card.append(body, ...(editor === null ? [] : [editor.root]), actions);
     host.appendChild(card);
     if (options.signal?.aborted === true) {
       // The run was cancelled before the card could ask; record the denial.
@@ -112,3 +140,63 @@ export function requestApproval(
     approve.focus();
   });
 }
+
+/** The editable-arguments region, or `null` when this card does not offer one. */
+function buildEditor(
+  request: ApprovalRequest,
+  options: ApprovalOptions,
+  strings: UiStrings,
+): { root: HTMLElement; commit: () => boolean } | null {
+  const { onEdit } = options;
+  if (onEdit === undefined || request.args === undefined) {
+    return null;
+  }
+  const original = JSON.stringify(request.args, null, 2);
+  const root = document.createElement("div");
+  root.className = "approval-edit";
+  root.setAttribute("part", "approval-edit");
+
+  const field = document.createElement("textarea");
+  field.className = "approval-args";
+  field.setAttribute("part", "approval-args");
+  field.setAttribute("aria-label", strings.approvalEditArgs);
+  field.rows = Math.min(10, original.split("\n").length);
+  field.value = original;
+
+  const error = document.createElement("div");
+  error.className = "approval-error";
+  error.setAttribute("part", "approval-error");
+  // A live region: it appears in response to pressing Approve, and a message
+  // that only exists visually leaves a screen-reader user with a button that
+  // silently did nothing.
+  error.setAttribute("role", "alert");
+  error.hidden = true;
+
+  root.append(field, error);
+  return {
+    root,
+    commit: () => {
+      if (field.value === original) {
+        return true;
+      }
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(field.value);
+      } catch {
+        error.textContent = strings.approvalArgsInvalid;
+        error.hidden = false;
+        field.focus();
+        return false;
+      }
+      if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        error.textContent = strings.approvalArgsNotAnObject;
+        error.hidden = false;
+        field.focus();
+        return false;
+      }
+      error.hidden = true;
+      onEdit(parsed as Record<string, unknown>);
+      return true;
+    },
+  };
+}

package/src/ui/checkpoint_menu.ts

@@ -1,5 +1,5 @@
 import type { RunRow } from "../core/run_index.js";
-import { relativeTime } from "./relative_time.js";
+import { type RelativeTimeFormatter, relativeTime } from "./relative_time.js";
 import { DEFAULT_UI_STRINGS, type UiStrings } from "./ui_strings.js";
 
 /** How the host continues a picked run. */
@@ -46,6 +46,7 @@ export class CheckpointMenu {
   readonly #heading: HTMLSpanElement;
   /** What had focus before the panel opened, restored on close. */
   #lastFocused: HTMLElement | null = null;
+  #formatRelativeTime: RelativeTimeFormatter | null = null;
   #strings: UiStrings;
   #runs: readonly RunRow[] = [];
 
@@ -91,6 +92,25 @@ export class CheckpointMenu {
   }
 
   /** Re-localize a panel built before the host's strings resolved. */
+  /**
+   * Replace the timestamp formatter, or restore the built-in with `null`.
+   *
+   * The built-in is deliberately locale-neutral -- there is no `Intl` anywhere
+   * in this component, so it never disagrees with a host's own formatting by
+   * guessing a locale. That is a defensible default and a poor requirement, so
+   * this is the way out.
+   */
+  setRelativeTimeFormatter(format: RelativeTimeFormatter | null): void {
+    this.#formatRelativeTime = format;
+  }
+
+  /** This row's timestamp, through the host's formatter when it set one. */
+  #formatTime(timestamp: number): string {
+    return this.#formatRelativeTime !== null
+      ? this.#formatRelativeTime(timestamp)
+      : relativeTime(timestamp, Date.now(), this.#strings);
+  }
+
   setStrings(strings: UiStrings): void {
     this.#strings = strings;
     this.element.setAttribute("aria-label", strings.checkpoints);
@@ -207,10 +227,7 @@ export class CheckpointMenu {
     row.setAttribute("part", "checkpoint-row");
 
     const preview = previewOf(run);
-    const time =
-      run.started_at === null
-        ? null
-        : relativeTime(Date.parse(run.started_at), Date.now(), this.#strings);
+    const time = run.started_at === null ? null : this.#formatTime(Date.parse(run.started_at));
 
     const label = document.createElement("span");
     label.className = "checkpoint-label";

package/src/ui/confirmation_card.ts

@@ -31,6 +31,16 @@ export interface ConfirmationOptions {
   signal?: AbortSignal;
   /** Localized strings; defaults to the English {@link DEFAULT_UI_STRINGS}. */
   strings?: UiStrings;
+  /**
+   * Offer a third button — "always allow, this session" — and call this when
+   * the user picks it. The card still resolves `true`: the extra decision is
+   * *in addition to* approving this call, not instead of it.
+   *
+   * Absent means no button, which is deliberate: presence of the handler is
+   * what enables it, so the affordance can never be rendered with nothing
+   * listening. A caller that cannot honour the waiver simply does not pass one.
+   */
+  onAlwaysAllow?: () => void;
 }
 
 /**
@@ -43,6 +53,12 @@ export interface ConfirmationOptions {
  * Answering it removes it: the record of the decision belongs to the tool card
  * this gates, which settles to `done` or `declined` and carries it. A spent
  * form left in place reads as still outstanding.
+ *
+ * With `onAlwaysAllow` set the card offers a third button. A prompt that is
+ * approved nearly every time is not a decision, it is a speed bump — and the
+ * reflex it trains is what makes the rare refusal easy to miss. Letting the
+ * user say "not this one again, this session" is the affordance that keeps the
+ * remaining prompts meaningful.
  */
 export function requestConfirmation(
   host: Node & ParentNode,
@@ -75,6 +91,10 @@ export function requestConfirmation(
     actions.setAttribute("part", "confirm-actions");
 
     const cancel = actionButton("cancel", strings.cancel);
+    const always =
+      options.onAlwaysAllow === undefined
+        ? null
+        : actionButton("always", strings.confirmAlways.replace("{tool}", request.toolName));
     const confirm = actionButton("confirm", strings.confirm);
 
     let settled = false;
@@ -93,9 +113,17 @@ export function requestConfirmation(
 
     cancel.addEventListener("click", () => close(false));
     confirm.addEventListener("click", () => close(true));
+    always?.addEventListener("click", () => {
+      // Recorded before resolving, so a caller that reads its own allowlist
+      // synchronously on the next call already sees this one.
+      options.onAlwaysAllow?.();
+      close(true);
+    });
     options.signal?.addEventListener("abort", () => close(false), { once: true });
 
-    actions.append(cancel, confirm);
+    // Confirm stays last, and rightmost: the waiver is the wider decision, and
+    // putting it where the eye lands for "yes" is how it gets taken by accident.
+    actions.append(cancel, ...(always === null ? [] : [always]), confirm);
     card.append(body, args, actions);
     host.appendChild(card);
     if (options.signal?.aborted === true) {

package/src/ui/message_actions.ts

@@ -0,0 +1,158 @@
+import type { UiStrings } from "./ui_strings.js";
+
+/** How long a button shows its confirmation before reverting. */
+const CONFIRM_MS = 1500;
+
+/** What an action bar can do, beyond copying. */
+export interface MessageActionsOptions {
+  /** Localized strings. */
+  strings: UiStrings;
+  /**
+   * The text Copy puts on the clipboard. A function rather than a string
+   * because a bubble's content is rewritten while it streams, and the bar is
+   * attached to the element rather than to a snapshot of it.
+   */
+  text: () => string;
+  /**
+   * Report a rating for this message. Absent means no feedback buttons.
+   *
+   * The component stores nothing: a rating is the host's to keep, and a
+   * write-only table nobody reads is not worth a schema.
+   */
+  onFeedback?: (rating: "up" | "down") => void;
+}
+
+/**
+ * Give one finished message bubble its row of actions.
+ *
+ * **Finished** is load-bearing. A streaming bubble reassigns its `innerHTML` on
+ * every delta, so anything attached mid-stream is discarded and rebuilt for
+ * each one -- the same constraint `attachCopyButtons` records, one level up.
+ *
+ * Retry is deliberately **not** here: it belongs to the last turn only, so the
+ * element owns it and moves it as the transcript grows. Everything on this bar
+ * is safe to offer on any message, however old.
+ *
+ * Idempotent -- a bubble already given a bar is skipped, so a re-render or a
+ * second call cannot stack rows.
+ */
+export function attachMessageActions(bubble: HTMLElement, options: MessageActionsOptions): void {
+  if (existingBar(bubble) !== null) {
+    return;
+  }
+  const bar = messageActionBar(bubble, options.strings);
+  bar.appendChild(copyButton(options));
+  if (options.onFeedback !== undefined) {
+    bar.append(
+      feedbackButton("up", options.strings.feedbackUp, options.onFeedback),
+      feedbackButton("down", options.strings.feedbackDown, options.onFeedback),
+    );
+  }
+}
+
+/**
+ * The empty action row on `bubble`, created if it has none yet.
+ *
+ * Shared so a bubble that wants *only* Retry -- a failed run, which has nothing
+ * worth copying and nothing to rate -- gets the same row, the same part name
+ * and the same accessible grouping as every other message, rather than a
+ * second thing that looks like one.
+ */
+export function messageActionBar(bubble: HTMLElement, strings: UiStrings): HTMLElement {
+  const existing = existingBar(bubble);
+  if (existing !== null) {
+    return existing;
+  }
+  const bar = document.createElement("div");
+  bar.className = "message-actions";
+  bar.setAttribute("part", "message-actions");
+  // A group rather than a toolbar: these are independent actions on the message
+  // above, not a set the user arrows between.
+  bar.setAttribute("role", "group");
+  bar.setAttribute("aria-label", strings.messageActions);
+  // A **sibling**, never a child. Inside the bubble the buttons join its
+  // `textContent`, which is what Copy reads, what history persists and what
+  // every existing assertion about a message's text compares against -- so an
+  // answer would be copied back with the glyphs of the buttons that copied it.
+  // The bubble must therefore already be in the tree when this is called.
+  bubble.after(bar);
+  return bar;
+}
+
+/** The action row belonging to `bubble`, if it has one. */
+function existingBar(bubble: HTMLElement): HTMLElement | null {
+  const next = bubble.nextElementSibling;
+  return next?.classList.contains("message-actions") === true ? (next as HTMLElement) : null;
+}
+
+/** Build one action button, labelled for screen readers rather than by glyph. */
+export function messageActionButton(
+  modifier: string,
+  label: string,
+  glyph: string,
+): HTMLButtonElement {
+  const button = document.createElement("button");
+  button.type = "button";
+  button.className = `message-action message-action--${modifier}`;
+  button.setAttribute("part", `message-action message-action-${modifier}`);
+  button.title = label;
+  button.setAttribute("aria-label", label);
+  const icon = document.createElement("span");
+  icon.setAttribute("aria-hidden", "true");
+  icon.textContent = glyph;
+  button.appendChild(icon);
+  return button;
+}
+
+function copyButton(options: MessageActionsOptions): HTMLButtonElement {
+  const { strings } = options;
+  const button = messageActionButton("copy", strings.copyMessage, "⎘");
+  button.addEventListener("click", () => {
+    void navigator.clipboard.writeText(options.text()).then(
+      () => flash(button, strings.copied, strings.copyMessage),
+      // A denied clipboard permission is the common case, not an exception:
+      // say so on the button rather than throwing into an unhandled rejection.
+      () => flash(button, strings.copyFailed, strings.copyMessage),
+    );
+  });
+  return button;
+}
+
+function feedbackButton(
+  rating: "up" | "down",
+  label: string,
+  report: (rating: "up" | "down") => void,
+): HTMLButtonElement {
+  const button = messageActionButton(
+    rating === "up" ? "up" : "down",
+    label,
+    rating === "up" ? "\u{1F44D}" : "\u{1F44E}",
+  );
+  button.addEventListener("click", () => {
+    // Pressed rather than removed: the rating is a standing statement about the
+    // message, and a button that vanishes leaves no record of what was said.
+    const pressed = button.getAttribute("aria-pressed") === "true";
+    button.setAttribute("aria-pressed", pressed ? "false" : "true");
+    report(rating);
+  });
+  button.setAttribute("aria-pressed", "false");
+  return button;
+}
+
+/**
+ * Flash `message` on the button, then restore `label`.
+ *
+ * The label to restore is passed rather than read back off the element: the
+ * caller is the one that set it, and reading it would introduce a null arm that
+ * cannot happen and cannot be covered.
+ */
+function flash(button: HTMLButtonElement, message: string, label: string): void {
+  button.title = message;
+  button.setAttribute("aria-label", message);
+  button.classList.add("message-action--confirmed");
+  setTimeout(() => {
+    button.title = label;
+    button.setAttribute("aria-label", label);
+    button.classList.remove("message-action--confirmed");
+  }, CONFIRM_MS);
+}

package/src/ui/page_quote_offer.ts

@@ -0,0 +1,215 @@
+import { quotableSelection } from "./quote_selection.js";
+
+/**
+ * The same select-then-offer gesture the transcript has, in the **host page**.
+ *
+ * This exists because the recipe version of it is a trap, and a specific one.
+ * Chrome reports the internal selection of an `<input>` or `<textarea>` through
+ * `document.getSelection()` as an ordinary `Range` whose endpoints are the
+ * field's *wrapper* -- not the field. So the text reads back perfectly and the
+ * range is indistinguishable from a selection over the surrounding prose: a
+ * host listening for a page selection quotes the user's own half-typed form
+ * field back at them, and nothing about the selection says why. The only signal
+ * is `document.activeElement`, which is not where anyone looks.
+ *
+ * That, plus "do not fire for the widget's own transcript, which already offers
+ * this", plus "a fixed-position affordance strands itself on the first scroll",
+ * is three non-obvious guards. Three guards is a component feature, not a
+ * documentation snippet.
+ */
+
+/** Pixels between a selection and the offer to quote it. */
+const GAP = 6;
+
+/**
+ * The offer's own appearance.
+ *
+ * Deliberately plain and deliberately overridable: this element lands in the
+ * host's page, not in our shadow tree, so it has no theme to inherit and no
+ * business imposing one. Everything here is a single class a host stylesheet
+ * outranks by adding one more selector.
+ */
+const OFFER_CSS = `
+.ag-ui-quote-offer {
+  position: fixed;
+  z-index: 2147483000;
+  transform: translate(-50%, -100%);
+  margin: 0;
+  padding: 0.25em 0.7em;
+  border: 1px solid rgb(0 0 0 / 0.15);
+  border-radius: 999px;
+  background: Canvas;
+  color: CanvasText;
+  font: inherit;
+  font-size: 0.8rem;
+  line-height: 1.6;
+  white-space: nowrap;
+  cursor: pointer;
+  box-shadow: 0 2px 10px rgb(0 0 0 / 0.18);
+}
+
+.ag-ui-quote-offer[data-below="true"] {
+  transform: translate(-50%, 0);
+}
+`;
+
+/** A live page-side offer. */
+export interface PageQuoteOffer {
+  /** The button itself, for a host that wants to style or inspect it. */
+  readonly element: HTMLButtonElement;
+  /** Stop offering: every listener removed, the button and its styles gone. */
+  detach(): void;
+}
+
+/** What {@link attachQuoteOffer} needs to know. */
+export interface PageQuoteOfferOptions {
+  /** Where a selection is worth offering to quote. */
+  within: HTMLElement;
+  /** What the offer says. */
+  label: string;
+  /**
+   * A subtree to stay out of -- the chat widget itself.
+   *
+   * Its transcript runs this same gesture on the inside, so without this a
+   * selection there would be offered twice and quoted twice.
+   */
+  exclude: Node;
+  /** Take the offer. */
+  onQuote: (text: string) => void;
+}
+
+/**
+ * Offer to quote what the user selects inside `within`.
+ *
+ * Nothing is quoted until the offer is taken -- which is the whole point. An
+ * automatic version of this is easy to write and horrible to use: every drag
+ * made to read, to copy, or to fix a typo silently appends to whatever the user
+ * was in the middle of typing.
+ */
+export function attachQuoteOffer(options: PageQuoteOfferOptions): PageQuoteOffer {
+  const { within, exclude, onQuote } = options;
+
+  // A constructed sheet rather than an injected `<style>`: a host with a strict
+  // `style-src` drops the second one silently, leaving an unstyled pill in the
+  // middle of their page. Per attachment rather than at module scope, which
+  // this package forbids.
+  const sheet = new CSSStyleSheet();
+  sheet.replaceSync(OFFER_CSS);
+  document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];
+
+  const button = document.createElement("button");
+  button.type = "button";
+  button.className = "ag-ui-quote-offer";
+  button.textContent = options.label;
+  button.hidden = true;
+  document.body.append(button);
+
+  let quoting = "";
+
+  const hide = (): void => {
+    button.hidden = true;
+    quoting = "";
+  };
+
+  const settled = (event: Event): void => {
+    // The widget's own gesture, tested on the **event path** rather than on the
+    // selection. The path crosses shadow boundaries and the selection does not:
+    // `Node.contains` is false for a node in a shadow tree, and the shadow-aware
+    // read, given no roots, hands back endpoints rescoped up into the page --
+    // so both selection-side tests would let a transcript drag through here and
+    // quote it a second time.
+    if (event.composedPath().includes(exclude)) {
+      hide();
+      return;
+    }
+    if (fieldHasFocus()) {
+      // The user is selecting inside their own form, to edit or to copy. See
+      // the module comment: nothing about the range itself says so.
+      hide();
+      return;
+    }
+    // The pointer's own coordinates, where there was one: they decide which
+    // line of a multi-line selection the offer hangs from.
+    const near = event instanceof MouseEvent ? { x: event.clientX, y: event.clientY } : undefined;
+    const selected = quotableSelection(within, [], near);
+    if (selected === null) {
+      hide();
+      return;
+    }
+    quoting = selected.text;
+    place(button, selected.rect);
+  };
+
+  const onMouseDown = (event: MouseEvent): void => {
+    if (!button.contains(event.target as Node)) {
+      hide();
+    }
+  };
+
+  within.addEventListener("mouseup", settled);
+  within.addEventListener("keyup", settled);
+  within.addEventListener("mousedown", onMouseDown);
+  // Capture, so a scrolling pane counts and not only the window: the offer is
+  // positioned in viewport coordinates, so anything that moves the words out
+  // from under it leaves it pointing at the wrong thing.
+  document.addEventListener("scroll", hide, true);
+  window.addEventListener("resize", hide);
+
+  // Without this the press collapses the selection before the click reads it.
+  button.addEventListener("mousedown", (event) => {
+    event.preventDefault();
+  });
+  button.addEventListener("click", () => {
+    const text = quoting;
+    window.getSelection()?.removeAllRanges();
+    hide();
+    onQuote(text);
+  });
+
+  return {
+    element: button,
+    detach(): void {
+      within.removeEventListener("mouseup", settled);
+      within.removeEventListener("keyup", settled);
+      within.removeEventListener("mousedown", onMouseDown);
+      document.removeEventListener("scroll", hide, true);
+      window.removeEventListener("resize", hide);
+      button.remove();
+      document.adoptedStyleSheets = document.adoptedStyleSheets.filter((each) => each !== sheet);
+    },
+  };
+}
+
+/**
+ * Whether focus is in something the user types into.
+ *
+ * `activeElement` rather than the selection, because the selection does not
+ * say. A focused shadow host reports as the host, which is why the widget's own
+ * composer is caught by the `exclude` subtree test instead -- the two guards
+ * each cover the other's blind spot.
+ */
+function fieldHasFocus(): boolean {
+  const active = document.activeElement;
+  if (active === null) {
+    return false;
+  }
+  return (
+    active.tagName === "INPUT" ||
+    active.tagName === "TEXTAREA" ||
+    (active as HTMLElement).isContentEditable === true
+  );
+}
+
+/** Float the offer beside `rect`, kept inside the viewport. */
+function place(button: HTMLButtonElement, rect: DOMRect): void {
+  // Unhidden first: a hidden element measures zero, and its own size decides
+  // both whether it fits above the selection and how far to pull it left.
+  button.hidden = false;
+  const below = rect.top < GAP + button.offsetHeight;
+  button.dataset["below"] = String(below);
+  button.style.top = `${below ? rect.bottom + GAP : rect.top - GAP}px`;
+  const half = button.offsetWidth / 2;
+  const centre = rect.left + rect.width / 2;
+  const width = document.documentElement.clientWidth;
+  button.style.left = `${Math.min(Math.max(centre, half), width - half)}px`;
+}