@artooi/ag-ui-web-component 0.44.0 → 0.46.0

package/src/ui/progress/tool_group_styles.ts

@@ -0,0 +1,232 @@
+// The folded tool-step group: one row per run of consecutive tool calls,
+// with the per-call cards one click down.
+
+/** The four per-call card modes, as attribute selectors on the host. */
+const CARD_MODES = [
+  '[data-tool-display="inline"]',
+  '[data-tool-display="minimal"]',
+  '[data-tool-display="compact"]',
+  '[data-tool-display="full"]',
+].join(", ");
+
+/**
+ * The host in grouped mode: any data-tool-display but the four card modes,
+ * which is how the element's toolDisplay getter reads it, so an absent or
+ * unknown value groups here as it does there. Wrapped in :where so it weighs
+ * what a bare :host weighs, and a theme restating a group rule on its own
+ * :host selector still wins at equal weight.
+ */
+const GROUPED = `:host(:where(:not(${CARD_MODES})))`;
+
+/** The host in one of the four card modes, where a group drawn earlier is flattened. */
+const CARDS = `:host(:is(${CARD_MODES}))`;
+
+export const TOOL_GROUP_STYLES: string = `
+/* ── The folded tool-step group ──────────────────────────────────
+   One quiet row per run of consecutive calls, the cards one click down as
+   plain lines rather than boxes. Every rule is scoped to grouped mode, so
+   none of it reaches a group drawn earlier once the host moves to a card
+   mode. */
+${GROUPED} .tool-group {
+  align-self: stretch;
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+}
+
+${GROUPED} .tool-group-head {
+  appearance: none;
+  align-self: flex-start;
+  max-width: 100%;
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  margin: 0 0 0 -6px;
+  padding: 4px 6px;
+  border: 0;
+  border-radius: 6px;
+  background: transparent;
+  color: var(--_muted);
+  font: inherit;
+  font-size: var(--_text-sm);
+  line-height: 1.3;
+  text-align: left;
+  cursor: pointer;
+}
+
+${GROUPED} .tool-group-head:hover {
+  background: var(--_hover);
+  color: var(--_fg);
+}
+
+${GROUPED} .tool-group-head:focus-visible {
+  outline: 2px solid var(--_ring);
+  outline-offset: 1px;
+}
+
+${GROUPED} .tool-group-label {
+  min-width: 0;
+  font-weight: 500;
+  color: var(--_ink-2);
+  overflow-wrap: anywhere;
+}
+
+${GROUPED} .tool-group-meta {
+  min-width: 0;
+  color: var(--_muted);
+  overflow-wrap: anywhere;
+}
+
+/* Each note opens with a middle dot, which also parts the first note from
+   the label. */
+${GROUPED} .tool-group-note::before {
+  content: "\\00B7";
+  margin: 0 6px 0 2px;
+}
+
+${GROUPED} .tool-group[data-state="error"] .tool-group-meta {
+  color: var(--_danger);
+}
+
+${GROUPED} .tool-group-icon {
+  flex: none;
+  box-sizing: border-box;
+  width: 14px;
+  height: 14px;
+  background: currentColor;
+  mask: var(--_ico-check) center / contain no-repeat;
+  color: var(--_success);
+}
+
+${GROUPED} .tool-group[data-state="error"] .tool-group-icon {
+  mask-image: var(--_ico-error);
+  color: var(--_danger);
+}
+
+${GROUPED} .tool-group[data-state="running"] .tool-group-icon {
+  mask: none;
+  background: none;
+  border: 2px solid var(--_muted);
+  border-top-color: transparent;
+  border-radius: 50%;
+  animation: ag-ui-tool-spin var(--_tool-spin-duration) linear infinite;
+}
+
+/* Waiting on the user: a steady accent dot rather than a spinner, and the
+   count in the accent's ink. */
+${GROUPED} .tool-group[data-state="waiting"] .tool-group-icon {
+  mask: none;
+  border-radius: 50%;
+  transform: scale(0.6);
+  background: var(--_accent);
+}
+
+${GROUPED} .tool-group[data-state="waiting"] .tool-group-meta {
+  color: var(--_accent-ink);
+  font-weight: 500;
+}
+
+${GROUPED} .tool-group-chevron {
+  flex: none;
+  width: 12px;
+  height: 12px;
+  background: currentColor;
+  mask: var(--_ico-chevron) center / contain no-repeat;
+  opacity: 0.7;
+  transition: transform var(--_motion) var(--_ease);
+}
+
+${GROUPED} .tool-group[data-open="true"] .tool-group-chevron {
+  transform: rotate(90deg);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  ${GROUPED} .tool-group[data-state="running"] .tool-group-icon {
+    animation: none;
+  }
+}
+
+${GROUPED} .tool-group-list {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  margin: 2px 0 4px 6px;
+  padding-left: 13px;
+  border-left: 1px solid var(--_border);
+}
+
+${GROUPED} .tool-group[data-open="false"] .tool-group-list {
+  display: none;
+}
+
+/* A card inside the group is one line of the list: icon, name, and its
+   Details control at the end, with the arguments and result opening under
+   the whole row. */
+${GROUPED} .tool-group .tool-call {
+  max-width: 100%;
+  align-self: stretch;
+  flex-flow: row wrap;
+  align-items: center;
+  gap: 2px 10px;
+  padding: 3px 0;
+  border: 0;
+  border-radius: 0;
+  background: transparent;
+  color: var(--_ink-2);
+  font-family: inherit;
+  font-size: var(--_text-sm);
+}
+
+${GROUPED} .tool-group .tool-call-head {
+  flex: 1 1 auto;
+  justify-content: flex-start;
+}
+
+${GROUPED} .tool-group .tool-call-name {
+  flex: 0 1 auto;
+  font-weight: 450;
+}
+
+/* The repeat ordinal on a step whose label an earlier step has. */
+${GROUPED} .tool-call-repeat {
+  color: var(--_muted);
+  font-variant-numeric: tabular-nums;
+}
+
+${GROUPED} .tool-group .tool-call-toggle {
+  font-family: inherit;
+  font-size: var(--_text-xs);
+  color: var(--_muted);
+}
+
+${GROUPED} .tool-group .tool-call-body,
+${GROUPED} .tool-group .tool-call-approval,
+${GROUPED} .tool-group .tool-call-subagent {
+  flex-basis: 100%;
+}
+
+/* Grouping is decided as each card is built, so a card mode set afterwards
+   finds groups already drawn. It flattens them: the group and its list stop
+   generating boxes, the row and the repeat ordinals go, and every card lays
+   out as a direct child of the answer, exactly as a card built in that mode
+   does. */
+${CARDS} .tool-group,
+${CARDS} .tool-group-list {
+  display: contents;
+}
+
+${CARDS} .tool-group-head,
+${CARDS} .tool-call-repeat {
+  display: none;
+}
+
+/* Each of these declares its own display, which beats the user-agent rule for
+   the hidden attribute, so each needs its own. The host prefix is there for
+   weight, not scope: it lifts these over the card-mode rules above that set
+   display, which are heavier than a bare class and attribute. */
+:host .tool-group[hidden],
+:host .tool-group-head[hidden],
+:host .tool-group-list[hidden] {
+  display: none;
+}
+`;

package/src/ui/progress/tool_step_group.ts

@@ -0,0 +1,269 @@
+import { SUBAGENT_PHASE, TOOL_CALL_STATUS } from "../../constants.js";
+import { fillUiString } from "../fill_ui_string.js";
+import type { UiStrings } from "../ui_strings.js";
+
+/** What a group says about itself, read by the shadow CSS from `data-state`. */
+type GroupState = "waiting" | "running" | "done" | "error";
+
+/** The statuses a step is still open in. */
+const OPEN_STATUSES: ReadonlySet<string> = new Set([
+  TOOL_CALL_STATUS.PENDING,
+  TOOL_CALL_STATUS.DEFERRED,
+]);
+
+/**
+ * A sub-agent panel still working, by the phase it stamps on itself. A panel
+ * outlives the delegation it drew, so a settled one does not match.
+ */
+const RUNNING_SUBAGENT = `.tool-call-subagent > .subagent:is(${[
+  SUBAGENT_PHASE.STARTED,
+  SUBAGENT_PHASE.TOOL_CALL,
+  SUBAGENT_PHASE.TOOL_RESULT,
+]
+  .map((phase) => `[data-phase="${phase}"]`)
+  .join(", ")})`;
+
+/** One step of the group: its card, and its label as the row names it. */
+interface Step {
+  readonly element: HTMLElement;
+  readonly name: string;
+  readonly label: string;
+}
+
+/**
+ * The attributes the row is drawn from: each card's `data-status`, its
+ * `data-asking` while a question or a confirmation is open on it, and the
+ * `data-phase` and `data-agent` a sub-agent panel stamps on itself inside the
+ * card that delegated to it. Watched rather than told, so a step settled,
+ * asked about or delegated by any path updates the row without the group being
+ * called.
+ */
+const WATCHED_ATTRIBUTES: readonly string[] = [
+  "data-status",
+  "data-asking",
+  "data-phase",
+  "data-agent",
+];
+
+/**
+ * Consecutive tool calls folded into one quiet row, "Worked through 5 steps",
+ * with the per-call cards one click down. Built by the transcript for each run
+ * of calls when the element's `toolDisplay` is `grouped`.
+ *
+ * The group owns no state of its own beyond its nodes and two facts: each
+ * step's label, and whether it has already opened itself for the current wait.
+ * Everything else is read back off the cards each time one changes.
+ *
+ * It opens itself while a step waits on the user, because a deferred step
+ * carries its approval prompt inside its card and a folded group would hide
+ * the very question it is asking. Once per wait, so the user can fold it
+ * again. A running sub-agent does not open it: the row names the sub-agent
+ * instead, beside the running mark.
+ */
+export class ToolStepGroup {
+  readonly element: HTMLDivElement;
+  readonly #strings: UiStrings;
+  readonly #list: HTMLDivElement;
+  readonly #head: HTMLButtonElement;
+  readonly #label: HTMLSpanElement;
+  readonly #meta: HTMLSpanElement;
+  /** The steps, in order. Cards only ever join a group, so this is its list's children. */
+  readonly #steps: Step[] = [];
+  /** Whether the group has already opened itself for the current wait. */
+  #openedForWait = false;
+
+  constructor(strings: UiStrings) {
+    this.#strings = strings;
+    this.element = document.createElement("div");
+    this.element.className = "tool-group";
+    this.element.setAttribute("part", "tool-group");
+    this.element.setAttribute("data-open", "false");
+
+    this.#head = document.createElement("button");
+    this.#head.type = "button";
+    this.#head.className = "tool-group-head";
+    this.#head.setAttribute("part", "tool-group-head");
+    this.#head.setAttribute("aria-expanded", "false");
+
+    const icon = document.createElement("span");
+    icon.className = "tool-group-icon";
+    icon.setAttribute("part", "tool-group-icon");
+    icon.setAttribute("aria-hidden", "true");
+
+    this.#label = document.createElement("span");
+    this.#label.className = "tool-group-label";
+    this.#label.setAttribute("part", "tool-group-label");
+
+    this.#meta = document.createElement("span");
+    this.#meta.className = "tool-group-meta";
+    this.#meta.setAttribute("part", "tool-group-meta");
+
+    const chevron = document.createElement("span");
+    chevron.className = "tool-group-chevron";
+    chevron.setAttribute("aria-hidden", "true");
+
+    this.#head.append(icon, this.#label, this.#meta, chevron);
+    this.#head.addEventListener("click", () => {
+      this.setOpen(this.element.getAttribute("data-open") !== "true");
+    });
+
+    this.#list = document.createElement("div");
+    this.#list.className = "tool-group-list";
+    this.#list.setAttribute("part", "tool-group-list");
+
+    this.element.append(this.#head, this.#list);
+
+    new MutationObserver(() => {
+      this.#refresh();
+    }).observe(this.#list, {
+      attributes: true,
+      attributeFilter: [...WATCHED_ATTRIBUTES],
+      subtree: true,
+    });
+  }
+
+  /**
+   * Add a card's element as the group's next step, under the label the card
+   * was built with.
+   *
+   * A step whose label an earlier step already has gets a repeat ordinal,
+   * "Fill field (2)", in an element of its own beside the card's name. The
+   * name itself is never rewritten, so a group flattened back into per-call
+   * cards by a card display mode shows exactly the label the card was built
+   * with, and the CSS hides the ordinal there.
+   */
+  add(card: HTMLElement, name: string): void {
+    const seen = this.#steps.filter((step) => step.name === name).length + 1;
+    let label = name;
+    if (seen > 1) {
+      const repeat = document.createElement("span");
+      repeat.className = "tool-call-repeat";
+      repeat.setAttribute("part", "tool-card-repeat");
+      repeat.textContent = fillUiString(this.#strings.toolStepRepeat, { n: seen });
+      card.querySelector(".tool-call-name")?.after(repeat);
+      label = `${name} ${repeat.textContent}`;
+    }
+    this.#steps.push({ element: card, name, label });
+    this.#list.append(card);
+    this.#refresh();
+  }
+
+  /** Show or hide the per-step cards. */
+  setOpen(open: boolean): void {
+    this.element.setAttribute("data-open", String(open));
+    this.#head.setAttribute("aria-expanded", String(open));
+  }
+
+  /**
+   * Open the group now, for the wait that is about to start.
+   *
+   * The group opens itself from its mutation observer, which runs a tick after
+   * the card is marked deferred. The approval prompt is drawn, and takes focus,
+   * in the same tick as the mark, while the list is still out of the layout: the
+   * focus is dropped and the scroll it would cause never happens. So the caller
+   * that is about to draw the prompt opens the group first, and this marks the
+   * wait as already answered for, so the observer's later refresh does not open
+   * it again over a user who folded it.
+   */
+  reveal(): void {
+    this.#openedForWait = true;
+    this.setOpen(true);
+  }
+
+  /**
+   * The row's note for a running sub-agent, naming it, or `null` when no step
+   * is delegating right now. Only a step that is itself still running counts.
+   */
+  #delegation(): string | null {
+    for (const { element } of this.#steps) {
+      const panel =
+        element.getAttribute("data-status") === TOOL_CALL_STATUS.PENDING
+          ? element.querySelector(RUNNING_SUBAGENT)
+          : null;
+      if (panel !== null) {
+        const agent = panel.getAttribute("data-agent");
+        return agent === null
+          ? this.#strings.subAgentWorking
+          : fillUiString(this.#strings.subAgentDelegatedTo, { agent });
+      }
+    }
+    return null;
+  }
+
+  #refresh(): void {
+    const strings = this.#strings;
+    const steps = this.#steps;
+    const statuses = steps.map((step) => step.element.getAttribute("data-status") ?? "");
+    const open = steps.filter((_, i) => OPEN_STATUSES.has(statuses[i] as string));
+    const count = (status: string): number => statuses.filter((s) => s === status).length;
+    const failed = count(TOOL_CALL_STATUS.ERROR);
+    const declined = count(TOOL_CALL_STATUS.DECLINED);
+    const deferred = count(TOOL_CALL_STATUS.DEFERRED);
+    // A step is waiting on the user when its approval is pending on the server,
+    // or when a question or confirmation is open on it. The second kind keeps
+    // its status at running, so it is read off its own flag.
+    const asking = steps.filter((step) => step.element.hasAttribute("data-asking")).length;
+    const waiting = deferred + asking;
+    const total = steps.length;
+
+    // Opens for a deferred step only. An approval renders inside its card, which
+    // a folded group would hide; a question or confirmation renders beside the
+    // group, in view, so there is nothing for it to open.
+    if (deferred > 0 && !this.#openedForWait) {
+      this.#openedForWait = true;
+      this.setOpen(true);
+    } else if (deferred === 0) {
+      this.#openedForWait = false;
+    }
+
+    let state: GroupState = "done";
+    if (waiting > 0) {
+      state = "waiting";
+    } else if (open.length > 0) {
+      state = "running";
+    } else if (failed > 0) {
+      state = "error";
+    }
+    this.element.setAttribute("data-state", state);
+    this.element.setAttribute("data-count", String(total));
+
+    const only = total === 1 ? steps[0] : undefined;
+    if (only !== undefined) {
+      this.#label.textContent = only.label;
+    } else {
+      const template =
+        state === "waiting"
+          ? strings.toolGroupSteps
+          : state === "running"
+            ? strings.toolGroupWorking
+            : strings.toolGroupWorked;
+      this.#label.textContent = fillUiString(template, { count: total });
+    }
+
+    const notes: string[] = [];
+    const delegation = this.#delegation();
+    const current = open[0];
+    if (waiting > 0) {
+      notes.push(fillUiString(strings.toolGroupWaiting, { count: waiting }));
+    } else if (delegation !== null) {
+      notes.push(delegation);
+    } else if (current !== undefined && total > 1) {
+      notes.push(current.label);
+    }
+    if (failed > 0) {
+      notes.push(fillUiString(strings.toolGroupFailed, { count: failed }));
+    }
+    if (declined > 0) {
+      notes.push(fillUiString(strings.toolGroupDeclined, { count: declined }));
+    }
+    this.#meta.replaceChildren(
+      ...notes.map((text) => {
+        const note = document.createElement("span");
+        note.className = "tool-group-note";
+        note.textContent = text;
+        return note;
+      }),
+    );
+    this.#meta.hidden = notes.length === 0;
+  }
+}