@artooi/ag-ui-web-component 0.9.0 → 0.11.0

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/relative_time.ts

@@ -6,15 +6,20 @@ import { DEFAULT_UI_STRINGS, type UiStrings } from "./ui_strings.js";
  *
  * `now` is injectable so callers (and tests) can pin the reference point; it
  * defaults to the current time. A timestamp in the future (clock skew) reads as
- * `"just now"`. The unit words come from {@link UiStrings} (the `{n}` token is
- * filled in here) so a localized host translates them; the bucketing stays
- * integer-rounded and locale-neutral.
+ * `"just now"`. A non-finite timestamp — an unparseable or missing `updated_at`
+ * that arrived as `NaN` — has no meaningful age, so it falls back to `justNow`
+ * rather than rendering `"NaNw ago"` or `"~2950w ago"`. The unit words come from
+ * {@link UiStrings} (the `{n}` token is filled in here) so a localized host
+ * translates them; the bucketing stays integer-rounded and locale-neutral.
  */
 export function relativeTime(
   timestamp: number,
   now: number = Date.now(),
   strings: UiStrings = DEFAULT_UI_STRINGS,
 ): string {
+  if (!Number.isFinite(timestamp)) {
+    return strings.justNow;
+  }
   const seconds = Math.round((now - timestamp) / 1000);
   if (seconds < 60) {
     return strings.justNow;

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);
       }

package/src/ui/styles.ts

@@ -146,7 +146,7 @@ export const STYLES = `
   --ag-ui-radius: 0;
 }
 
-/* Page (PAGE-1): full-bleed background with a centred reading column. Unlike
+/* Page: full-bleed background with a centred reading column. Unlike
    "full" (edge-to-edge, left-aligned messages) the content sits in a column
    capped at --ag-ui-content-max-width. The column is produced by symmetric auto
    padding on the scroll area + composer (no per-row wrapper), so user pills
@@ -188,7 +188,7 @@ export const STYLES = `
   max-width: 100%;
 }
 
-/* Sidebar (CUST-3): a full-height docked panel that slides open/closed and
+/* Sidebar: a full-height docked panel that slides open/closed and
    collapses to a slim icon rail (not the floating launcher). Docked right by
    default; data-side="left" docks it left. Overlay by default — set
    --ag-ui-position: static (and place this element in your own layout) for a
@@ -298,7 +298,7 @@ export const STYLES = `
   white-space: nowrap;
 }
 
-/* Header / launcher icon holder (CUST-2): a slot, with a data-icon-url <img>
+/* Header / launcher icon holder: a slot, with a data-icon-url <img>
    fallback, sized via --ag-ui-icon-size. */
 .icon-holder {
   display: inline-flex;
@@ -372,7 +372,7 @@ export const STYLES = `
   gap: var(--ag-ui-space);
 }
 
-/* Empty-state region (CUST-1 slot): centred while it's the only thing in the
+/* Empty-state region (slot): centred while it's the only thing in the
    list, hidden as soon as a message, card, or pending indicator renders. */
 .empty {
   margin: auto;
@@ -384,7 +384,7 @@ export const STYLES = `
   display: none;
 }
 
-/* ── Answer group / well (WELL-1) ─────────────────────────────────────────
+/* ── Answer group / well ─────────────────────────────────────────
    One .answer per assistant turn wraps the streamed text, its tool cards,
    and the pending indicator so a whole answer reads (and can be boxed) as one
    unit. A flex column on the message-list gap, stretched to the list width so
@@ -553,7 +553,7 @@ export const STYLES = `
   }
 }
 
-/* ── Thoughts region (THINK-1) ────────────────────────────────────────────
+/* ── Thoughts region ────────────────────────────────────────────
    A muted, collapsible chain-of-thought at the top of the answer group: open
    while the model reasons, folded once the answer text starts. */
 .thoughts {
@@ -646,7 +646,7 @@ export const STYLES = `
   word-break: break-word;
 }
 
-/* Leading status icon (CARD-1). Empty in the DOM — the glyph/spinner is drawn
+/* Leading status icon. Empty in the DOM — the glyph/spinner is drawn
    here from the card's data-status, so it stays themeable. */
 .tool-call-icon {
   flex: none;
@@ -694,7 +694,7 @@ export const STYLES = `
   }
 }
 
-/* Inline display mode (CARD-1): the lightest card — drop the box chrome so the
+/* Inline display mode: the lightest card — drop the box chrome so the
    status row reads as one line of the answer; the result toggle still expands
    below it. */
 .tool-call[data-display="inline"] {
@@ -824,7 +824,7 @@ export const STYLES = `
   display: none;
 }
 
-/* The 🎤 mic button (VOICE-1); shown only once #wireVoice mounts it. */
+/* The 🎤 mic button; shown only once #wireVoice mounts it. */
 .voice-slot {
   display: contents;
 }
@@ -1028,6 +1028,127 @@ export const STYLES = `
   color: #ffffff;
 }
 
+/* Approval card — the server-side-tool gate (approve/deny an interrupt). */
+.approval {
+  align-self: stretch;
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 12px;
+  background: var(--ag-ui-bg);
+  border: 1px solid var(--ag-ui-accent);
+  border-radius: 10px;
+}
+
+.approval[data-resolved] {
+  opacity: 0.7;
+  border-color: var(--ag-ui-border);
+}
+
+.approval-body {
+  font-weight: 600;
+}
+
+.approval-actions {
+  display: flex;
+  gap: 8px;
+  justify-content: flex-end;
+}
+
+.approval-btn {
+  border: 1px solid var(--ag-ui-border);
+  border-radius: 8px;
+  padding: 8px 14px;
+  font: inherit;
+  font-weight: 600;
+  cursor: pointer;
+  background: var(--ag-ui-bg);
+  color: var(--ag-ui-fg);
+}
+
+.approval-btn:disabled {
+  cursor: default;
+  opacity: 0.6;
+}
+
+.approval-btn--approve {
+  border-color: var(--ag-ui-accent);
+  background: var(--ag-ui-accent);
+  color: #ffffff;
+}
+
+/* Question card — the built-in ask_user prompt (radios and/or free text). */
+.question {
+  align-self: stretch;
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 12px;
+  background: var(--ag-ui-bg);
+  border: 1px solid var(--ag-ui-accent);
+  border-radius: 10px;
+}
+
+.question[data-resolved] {
+  opacity: 0.7;
+  border-color: var(--ag-ui-border);
+}
+
+.question-body {
+  font-weight: 600;
+}
+
+.question-options {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+
+.question-choice {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  cursor: pointer;
+}
+
+.question-input {
+  box-sizing: border-box;
+  width: 100%;
+  padding: 8px 10px;
+  font: inherit;
+  color: var(--ag-ui-fg);
+  background: var(--ag-ui-bg);
+  border: 1px solid var(--ag-ui-border);
+  border-radius: 8px;
+}
+
+.question-input:disabled {
+  opacity: 0.6;
+}
+
+.question-actions {
+  display: flex;
+  justify-content: flex-end;
+}
+
+.question-btn {
+  border: 1px solid var(--ag-ui-accent);
+  border-radius: 8px;
+  padding: 8px 14px;
+  font: inherit;
+  font-weight: 600;
+  cursor: pointer;
+  background: var(--ag-ui-accent);
+  color: #ffffff;
+}
+
+.question-btn:disabled {
+  cursor: default;
+  opacity: 0.6;
+}
+
 /* Skills — chips row + the /-command palette, above the input. */
 .skill-chips {
   display: flex;

package/src/ui/thoughts_block.ts

@@ -2,9 +2,9 @@ import { DEFAULT_UI_STRINGS, type UiStrings } from "./ui_strings.js";
 
 /**
  * A muted, collapsible "thinking" region for a reasoning model's streamed
- * chain-of-thought (THINK-1).
+ * chain-of-thought.
  *
- * Lives at the top of the current answer group (the WELL-1 turn container): it
+ * Lives at the top of the current answer group (the turn container): it
  * opens expanded while the model reasons — {@link stream} replaces its body with
  * the running reasoning buffer — and {@link collapse} folds it away once the
  * answer's first text token arrives, so the thoughts don't crowd the answer.
@@ -42,6 +42,7 @@ export class ThoughtsBlock {
 
     this.#label = document.createElement("span");
     this.#label.className = "thoughts-label";
+    this.#label.setAttribute("part", "thoughts-label");
     this.#label.textContent = strings.thinking;
     this.#toggle.append(this.#label);