@artooi/agents-web-components 0.0.0-stage → 0.1.0

package/src/ui/progress/tool_group_styles.ts

@@ -0,0 +1,313 @@
+// 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}))`;
+
+/**
+ * A card inside an opened group, with the host in grouped mode and the given
+ * data-tool-group-display. The inner attribute sits inside the same :host()
+ * as the grouped test, since the host is featureless outside it, and being
+ * grouped-only is what lets an outer card mode flatten the group into its own
+ * cards: none of these rules match there. Full is no rule at all, so an absent
+ * or unknown inner value draws the full card a group always drew.
+ */
+function inner(mode: string): string {
+  return `:host(:where(:not(${CARD_MODES}))[data-tool-group-display="${mode}"]) .tool-group-list .tool-call`;
+}
+
+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:not(:disabled):hover {
+  background: var(--_hover);
+  color: var(--_fg);
+}
+
+/* A one-step row with nothing behind it -- a call with no arguments and no
+   result yet, or a blank one -- is a label, not a control: the step group
+   disables it and drops its expanded state, and this drops the pointer and
+   the chevron. Disabled rather than enabled-and-inert, so it takes no focus. */
+${GROUPED} .tool-group-head:disabled {
+  cursor: default;
+}
+
+${GROUPED} .tool-group-head:disabled .tool-group-chevron {
+  display: none;
+}
+
+${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. Its ink is the second ink in every theme, unless the host
+   set the tool token, which then reaches the grouped calls too. */
+${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(--_tool-fg-set, 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%;
+}
+
+/* The inner display mode: how an opened group draws its calls. The same
+   visibility rules the card modes apply to a flat card, so a call inside the
+   group shows the regions the flat card of that mode shows. The flat inline
+   mode's chrome rule is left out on purpose: a card in the group has already
+   lost its box and is laid out as a row of the list, and that rule's padding
+   and gap would undo the row. Selected from the host attribute, so changing it
+   restyles groups already on screen. */
+${inner("compact")}[data-expanded="false"] .tool-call-section {
+  display: none;
+}
+
+${inner("inline")} .tool-call-section--args {
+  display: none;
+}
+
+${inner("minimal")} .tool-call-toggle,
+${inner("minimal")} .tool-call-body {
+  display: none;
+}
+
+/* The toggle over nothing, as the card modes refuse it: under every inner mode
+   but compact the arguments are not behind the toggle, so a call whose result
+   is missing or blank has nothing for it to open. */
+:host(:where(:not(${CARD_MODES})):not([data-tool-group-display="compact"])) .tool-group-list .tool-call:not([data-has-result]) .tool-call-toggle {
+  display: none;
+}
+
+/* A call waiting on an approval shows its arguments in every inner mode, as it
+   does in every card mode, and for the same reason: the arguments are what
+   tell three gated calls of one tool apart. These come after the hides above,
+   which they tie with on weight. The arguments region only, never every
+   section, since the result region carries the hidden attribute until a
+   result exists and a display value here would override it. The arguments
+   region carries it too when the call has none, so it is excluded while
+   hidden rather than framed empty. */
+${inner("minimal")}[data-status="deferred"] .tool-call-body {
+  display: flex;
+}
+
+${inner("compact")}[data-status="deferred"] .tool-call-section--args:not([hidden]),
+${inner("inline")}[data-status="deferred"] .tool-call-section--args:not([hidden]) {
+  display: flex;
+}
+
+/* A one-step group already names its call in the row, so the card's own head
+   is not drawn inside it. Under the minimal inner mode a card is only its head,
+   so the row has nothing to open onto and draws no chevron. Grouped-only, so a
+   card mode keeps the head. data-count is rewritten live as a run grows. */
+${GROUPED} .tool-group[data-count="1"] .tool-call-head {
+  display: none;
+}
+
+:host(:where(:not(${CARD_MODES}))[data-tool-group-display="minimal"]) .tool-group[data-count="1"] .tool-group-chevron {
+  display: none;
+}
+
+/* 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,317 @@
+import {
+  SUBAGENT_PHASE,
+  TOOL_CALL_STATUS,
+  TOOL_GROUP_DISPLAY,
+  type ToolGroupDisplayMode,
+} 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, its
+ * `data-has-result` once a result with text arrived, 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-has-result",
+  "data-phase",
+  "data-agent",
+];
+
+/**
+ * Whether a lone step's card has anything to show under the row, which hides
+ * the card's own head: arguments, a result with text, an approval prompt (drawn
+ * while the call is deferred) or a sub-agent's progress. Which of the first two
+ * the inner display draws decides which count: inline draws no arguments, and
+ * minimal draws neither, so a call is not offered over what it would not show.
+ */
+function hasDetails(card: HTMLElement, display: ToolGroupDisplayMode): boolean {
+  const minimal = display === TOOL_GROUP_DISPLAY.MINIMAL;
+  const args = !minimal && display !== TOOL_GROUP_DISPLAY.INLINE;
+  return (
+    (args && card.hasAttribute("data-has-args")) ||
+    (!minimal && card.hasAttribute("data-has-result")) ||
+    card.getAttribute("data-status") === TOOL_CALL_STATUS.DEFERRED ||
+    card.querySelector(".tool-call-subagent > *") !== null
+  );
+}
+
+/**
+ * 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 #display: () => ToolGroupDisplayMode;
+  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, display: () => ToolGroupDisplayMode) {
+    this.#strings = strings;
+    this.#display = display;
+    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));
+  }
+
+  /**
+   * Offer the row as a disclosure only while something is behind it. Several
+   * steps always are, since each shows its own head; a lone step's head is not
+   * drawn in the group, so the row is a label until its card has details. A
+   * row that loses them, a gated call with no arguments once it is answered,
+   * folds as it goes.
+   */
+  #setExpandable(expandable: boolean): void {
+    this.#head.disabled = !expandable;
+    if (expandable) {
+      this.#head.setAttribute("aria-expanded", this.element.getAttribute("data-open") as string);
+      return;
+    }
+    this.element.setAttribute("data-open", "false");
+    this.#head.removeAttribute("aria-expanded");
+  }
+
+  /**
+   * 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;
+  }
+
+  /** Redraw the row from the cards, for a change the cards do not announce. */
+  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);
+    // The state is also a part, because `::part()` takes no attribute selector;
+    // the whole list is rewritten so the old modifier goes.
+    this.element.setAttribute("part", `tool-group tool-group-${state}`);
+    this.element.setAttribute("data-count", String(total));
+
+    const only = total === 1 ? steps[0] : undefined;
+    this.#setExpandable(only === undefined || hasDetails(only.element, this.#display()));
+    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;
+  }
+}