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

package/src/ui/progress/tool_step_styles.ts

@@ -0,0 +1,472 @@
+// Tool steps: the per-call card in each display mode, its status glyphs, and
+// the sub-agent progress a delegating card holds. The skill palette's token
+// mark sits among them only because no rule moved in the split.
+export const TOOL_STEP_STYLES: string = `
+.tool-call {
+  align-self: flex-start;
+  max-width: 80%;
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  font-size: 12px;
+  font-family: ui-monospace, "SF Mono", Menlo, monospace;
+  padding: 8px 10px;
+  border-radius: 8px;
+  background: var(--_tool-bg);
+  border: 1px solid var(--_border);
+  color: var(--_tool-fg);
+}
+
+/* Wraps, because the name is the only flexible child and every badge the row
+   gains is taken out of it. An approved call adds a third fixed badge, which in
+   a sidebar-width panel left the name 37px and broke it mid-word. Badges drop to
+   their own row instead. */
+.tool-call-head {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+}
+
+.tool-call-name {
+  /* An auto basis, and a min-width floor rather than zero: the name may shrink,
+     but not below something readable, so wrapping moves a badge instead of
+     shredding a word. Breaking anywhere still applies to a name that cannot fit
+     on a line of its own, which is what keeps a long unbroken tool name inside
+     the card. */
+  flex: 1 1 auto;
+  min-width: 6ch;
+  font-weight: 600;
+  overflow-wrap: anywhere;
+}
+
+/* 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;
+  box-sizing: border-box;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 14px;
+  height: 14px;
+  font-size: 12px;
+  line-height: 1;
+}
+
+/* Pending: a real spinning ring. Speed is tunable; reduced motion stops it. */
+.tool-call[data-status="pending"] .tool-call-icon {
+  border: 2px solid var(--_muted);
+  border-top-color: transparent;
+  border-radius: 50%;
+  animation: ag-ui-tool-spin var(--_tool-spin-duration) linear infinite;
+}
+
+@keyframes ag-ui-tool-spin {
+  to { transform: rotate(360deg); }
+}
+
+/* Deferred: no spinner, because nothing is spinning. A steady accent dot, since
+   the state is waiting-on-you rather than an outcome. */
+.tool-call[data-status="deferred"] .tool-call-icon {
+  border-radius: 50%;
+  background: var(--_accent);
+}
+
+/* Settled: a themeable glyph coloured by outcome. */
+.tool-call[data-status="done"] .tool-call-icon::before {
+  content: var(--_tool-icon-done);
+  color: var(--_success);
+}
+
+.tool-call[data-status="error"] .tool-call-icon::before {
+  content: var(--_tool-icon-error);
+  color: var(--_danger);
+}
+
+.tool-call[data-status="declined"] .tool-call-icon::before {
+  content: var(--_tool-icon-declined);
+  color: var(--_muted);
+}
+
+/* Not finished: muted like declined, since nothing failed, but its own glyph,
+   since nobody refused it either. */
+.tool-call[data-status="interrupted"] .tool-call-icon::before {
+  content: var(--_tool-icon-interrupted);
+  color: var(--_muted);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .tool-call[data-status="pending"] .tool-call-icon {
+    animation: none;
+  }
+}
+
+/* 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. */
+:host([data-tool-display="inline"]) .tool-call {
+  max-width: 100%;
+  background: transparent;
+  border: none;
+  padding: 2px 0;
+  gap: 2px;
+}
+
+.tool-call-status {
+  flex: none;
+  padding: 1px 8px;
+  border-radius: 999px;
+  font-size: 11px;
+  font-weight: 600;
+  background: rgba(127, 127, 127, 0.16);
+  color: var(--_muted);
+}
+
+.tool-call[data-status="deferred"] .tool-call-status {
+  color: var(--_accent);
+}
+
+.tool-call[data-status="done"] .tool-call-status {
+  color: var(--_success);
+}
+
+.tool-call[data-status="error"] .tool-call-status {
+  color: var(--_danger);
+}
+
+.tool-call[data-status="declined"] .tool-call-status,
+.tool-call[data-status="interrupted"] .tool-call-status {
+  color: var(--_muted);
+}
+
+.tool-call-body {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+
+.tool-call-section {
+  display: flex;
+  flex-direction: column;
+  gap: 3px;
+}
+
+/* A call with no arguments drops the region rather than framing an empty
+   object, and a settled card drops the result region until it has one -- both
+   by setting the hidden property, and an author display beats the user-agent
+   rule for that attribute. Without this the region kept laying out: 42px of
+   card holding the ARGUMENTS heading over nothing, on every call the agent
+   made with no arguments, in the display mode that shows arguments by
+   default. */
+.tool-call-section[hidden] {
+  display: none;
+}
+
+/* The heading that tells the two payloads apart. Without it the arguments and
+   the result were one run of text and a reader had to guess the boundary. */
+.tool-call-section-label {
+  font-size: 10px;
+  font-weight: 700;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  color: var(--_muted);
+}
+
+.skill-item-token {
+  font-family: ui-monospace, "SF Mono", Menlo, monospace;
+  font-size: 0.92em;
+  color: var(--_accent);
+  margin-right: 6px;
+}
+
+/* The lasting record of a human decision on a gated call — without it an
+   approved call looks exactly like one that was never gated. */
+.tool-call-decision {
+  flex: none;
+  font-size: 11px;
+  font-style: italic;
+  color: var(--_muted);
+}
+
+.tool-call-args,
+.tool-call-result {
+  margin: 0;
+  padding: 6px 8px;
+  max-height: 160px;
+  overflow: auto;
+  background: var(--_bg);
+  border: 1px solid var(--_border);
+  border-radius: 6px;
+  white-space: pre-wrap;
+  word-break: break-word;
+  color: var(--_fg);
+}
+
+/* A region a host formatter took over, marked by the card. Preformatted
+   whitespace is what makes the built-in block read as written, and it is the one
+   thing a host cannot want: a table inherits it as mangled cell spacing, and a
+   sentence as line breaks nobody typed.
+
+   Whitespace only. The card's own face, frame, padding and scroll cap stay,
+   because the card is one visual object -- the head row and the status pill are
+   monospaced too -- and a region that dropped the family would be the only part
+   of it wearing a different one. A host that wants that restyles the
+   tool-card-result part, which does not need the formatter at all. */
+.tool-call-args[data-formatted],
+.tool-call-result[data-formatted] {
+  white-space: normal;
+}
+
+/* Display modes are pure visibility over one DOM shape, selected from the host
+   attribute rather than a value stamped on the card at build time, so flipping
+   data-tool-display re-styles cards already on screen. See ToolCallCard.
+
+   Default (no attribute) is the full mode: arguments always visible, result
+   behind the toggle. */
+.tool-call[data-expanded="false"] .tool-call-section--result {
+  display: none;
+}
+
+/* Compact: one toggle over both regions, so a settled card is a single line
+   until asked. */
+:host([data-tool-display="compact"]) .tool-call[data-expanded="false"] .tool-call-section {
+  display: none;
+}
+
+/* Inline: the result only; the call's arguments are noise at this density. */
+:host([data-tool-display="inline"]) .tool-call .tool-call-section--args {
+  display: none;
+}
+
+/* Minimal: the status row and nothing else, so there is no toggle to press. */
+:host([data-tool-display="minimal"]) .tool-call .tool-call-toggle,
+:host([data-tool-display="minimal"]) .tool-call .tool-call-body {
+  display: none;
+}
+
+/* A pending card has no result yet, and in the modes where the arguments are
+   hidden too there is nothing behind the toggle. Hide the control rather than
+   offer one that expands onto nothing. A deferred card is the same, and its
+   arguments are shown unconditionally by the rules below. */
+.tool-call[data-status="pending"] .tool-call-toggle,
+.tool-call[data-status="deferred"] .tool-call-toggle,
+:host([data-tool-display="inline"]) .tool-call[data-status="pending"] .tool-call-toggle {
+  display: none;
+}
+
+/* The approval prompt for a gated call, rendered inside that call's own card.
+   Empty on every card nobody is being asked about, so it collapses instead of
+   adding a gap to each one. */
+.tool-call-approval:empty {
+  display: none;
+}
+
+.tool-call-approval {
+  margin-top: 8px;
+}
+
+/* A card that is asking a question shows what it is asking about, in every
+   display mode. Three gated calls of one tool ask the same words, so the
+   arguments are the only thing telling them apart, and a density setting must
+   not be able to hide the answer to "which one is this". */
+:host([data-tool-display="minimal"]) .tool-call[data-status="deferred"] .tool-call-body {
+  display: flex;
+}
+
+/* The arguments region only, never every section: the result region carries the
+   hidden attribute until a result exists, and a display value here overrides it,
+   framing an empty RESULT heading under the question. */
+:host([data-tool-display="compact"]) .tool-call[data-status="deferred"] .tool-call-section--args,
+:host([data-tool-display="inline"]) .tool-call[data-status="deferred"] .tool-call-section--args {
+  display: flex;
+}
+
+/* A delegated sub-agent's progress, inside the card that delegated. Empty on
+   every card that delegated nothing, so it collapses rather than adding a gap
+   to each one -- the same shape the approval slot uses. */
+.tool-call-subagent:empty {
+  display: none;
+}
+
+.tool-call-subagent {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.subagent {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  min-width: 0;
+}
+
+/* The collapsed row is the status and the expander at once, which is what keeps
+   a ten-step child one row until somebody opens it. Full width and left-aligned,
+   because it is a line of the card rather than a button on it. */
+.subagent-row {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  width: 100%;
+  box-sizing: border-box;
+  padding: 2px 0;
+  border: none;
+  background: none;
+  font: inherit;
+  text-align: left;
+  color: var(--_muted);
+  cursor: pointer;
+}
+
+/* Nothing behind the row yet -- a delegation that failed before calling
+   anything. Drop the affordances rather than offer a control that expands onto
+   an empty region, which is the refusal the card's own toggle already makes. */
+.subagent-row:disabled {
+  cursor: default;
+}
+
+.subagent-row::after {
+  content: var(--_disclosure-collapsed);
+  flex: none;
+  margin-left: auto;
+  color: var(--_accent);
+}
+
+.subagent-row[aria-expanded="true"]::after {
+  content: var(--_disclosure-expanded);
+}
+
+.subagent-row:disabled::after {
+  display: none;
+}
+
+/* Empty in the DOM; the glyph is drawn here from the panel's data-phase, so a
+   host re-themes it through the same tool-icon custom properties the card uses. */
+.subagent-icon {
+  flex: none;
+  box-sizing: border-box;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 10px;
+  height: 10px;
+  font-size: 10px;
+  line-height: 1;
+}
+
+/* Anything that is not a terminal phase is the child still working. Selected by
+   what it is not, so a phase this client has not heard of still spins rather
+   than rendering as a blank. */
+.subagent[data-phase]:not([data-phase="finished"]):not([data-phase="failed"]) .subagent-icon {
+  border: 2px solid var(--_muted);
+  border-top-color: transparent;
+  border-radius: 50%;
+  animation: ag-ui-tool-spin var(--_tool-spin-duration) linear infinite;
+}
+
+.subagent[data-phase="finished"] .subagent-icon::before {
+  content: var(--_tool-icon-done);
+  color: var(--_success);
+}
+
+.subagent[data-phase="failed"] .subagent-icon::before {
+  content: var(--_tool-icon-error);
+  color: var(--_danger);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .subagent .subagent-icon {
+    animation: none;
+  }
+}
+
+/* The server's own pre-rendered line. Shrinks and wraps rather than pushing the
+   chevron out of the card, which is what a fixed-width sibling in a flex row
+   does to a panel at sidebar width. */
+.subagent-status {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow-wrap: anywhere;
+}
+
+/* The child's own calls. Indented and ruled, so the nesting is visible without
+   a second card frame around it. */
+.subagent-steps {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  margin-left: 4px;
+  padding-left: 10px;
+  border-left: 1px solid var(--_border);
+}
+
+.subagent-steps[hidden] {
+  display: none;
+}
+
+.subagent-step {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  min-width: 0;
+  color: var(--_muted);
+}
+
+.subagent-step-icon {
+  flex: none;
+  box-sizing: border-box;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 8px;
+  height: 8px;
+  font-size: 9px;
+  line-height: 1;
+}
+
+/* No outcome yet: the wire says null while the call is in flight, and the
+   absence of the attribute is how that arrives here. A hollow ring, not a
+   spinner -- several can be on screen at once and the row above already spins. */
+.subagent-step:not([data-ok]) .subagent-step-icon {
+  border: 1px solid var(--_muted);
+  border-radius: 50%;
+}
+
+.subagent-step[data-ok="true"] .subagent-step-icon::before {
+  content: var(--_tool-icon-done);
+  color: var(--_success);
+}
+
+.subagent-step[data-ok="false"] .subagent-step-icon::before {
+  content: var(--_tool-icon-error);
+  color: var(--_danger);
+}
+
+.subagent-step-name {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow-wrap: anywhere;
+}
+
+.tool-call-toggle {
+  align-self: flex-start;
+  border: none;
+  padding: 0;
+  background: none;
+  font: inherit;
+  font-weight: 600;
+  color: var(--_accent);
+  cursor: pointer;
+}
+
+.tool-call-toggle::before {
+  content: var(--_disclosure-collapsed) " ";
+}
+
+.tool-call-toggle[aria-expanded="true"]::before {
+  content: var(--_disclosure-expanded) " ";
+}
+`;

package/src/ui/shell/adopt_styles.ts

@@ -16,13 +16,19 @@ import { STYLES } from "../styles.js";
  * Per instance is no worse than the `<style>` element it replaces, which also
  * parsed once per mount.
  *
+ * `extra` is the element's `extraStyles`, adopted after the built-in sheet so
+ * a host's rules win at equal specificity. They are constructed sheets too, so
+ * they inherit the same CSP immunity.
+ *
  * No fallback: constructible `CSSStyleSheet` is Chrome 73, Firefox 101 and
- * Safari 16.4, all below this package's declared Safari 17 runtime target. A
- * guard here would be code no supported browser can reach, and the only way
- * to keep it would be to exempt it from the coverage gate.
+ * Safari 16.4, all below this package's browser floor (Chrome 123, Firefox
+ * 120, Safari 17.5). A guard here would be code no supported browser can
+ * reach, and the only way to keep it would be to exempt it from the coverage
+ * gate.
  */
-export function adoptStyles(root: ShadowRoot): void {
+export function adoptStyles(root: ShadowRoot, extra: readonly CSSStyleSheet[] = []): CSSStyleSheet {
   const sheet = new CSSStyleSheet();
   sheet.replaceSync(STYLES);
-  root.adoptedStyleSheets = [sheet];
+  root.adoptedStyleSheets = [sheet, ...extra];
+  return sheet;
 }

package/src/ui/shell/build_header.ts

@@ -0,0 +1,108 @@
+import type { UiStrings } from "../ui_strings.js";
+import { headerButton } from "./header_button.js";
+import { iconElement } from "./icon_element.js";
+
+/** What {@link buildHeader} needs from the element that owns the header. */
+export interface HeaderOptions {
+  /** The element itself, asked whether a host slotted an icon. */
+  readonly host: HTMLElement;
+  /** The title node, kept by the element so a later `title-text` can update it. */
+  readonly title: HTMLElement;
+  readonly titleText: string;
+  readonly iconUrl: string | null;
+  readonly strings: UiStrings;
+  /** Whether the server indexes runs, so there is anything to continue. */
+  readonly withCheckpoints: boolean;
+  /** The opt-in theme toggle, or `null` when the host did not ask for one. */
+  readonly themeToggle: HTMLButtonElement | null;
+  readonly signal: AbortSignal;
+  readonly onHistory: () => void;
+  readonly onCheckpoints: () => void;
+  readonly onNewChat: () => void;
+  readonly onCollapse: () => void;
+  readonly onToggleTheme: () => void;
+}
+
+/** The header, and the one control the element still needs a handle on. */
+export interface BuiltHeader {
+  readonly header: HTMLElement;
+  /**
+   * The checkpoints button, built whether or not it is shown: the click-away
+   * handler for the checkpoints popover has to exclude it either way.
+   */
+  readonly checkpoints: HTMLButtonElement;
+}
+
+/**
+ * Build the panel's title bar: the optional icon, the title, the host's
+ * header-actions slot, and the controls.
+ *
+ * Every control calls back into the element's public methods, so a host
+ * chrome driving them imperatively takes exactly the path the built-in button
+ * takes.
+ */
+export function buildHeader(options: HeaderOptions): BuiltHeader {
+  const { strings } = options;
+  const header = document.createElement("div");
+  header.className = "header";
+  header.setAttribute("part", "header");
+
+  const title = options.title;
+  title.className = "header-title";
+  title.setAttribute("part", "title");
+  title.textContent = options.titleText;
+
+  // Optional header icon: a slot (any markup) with a `data-icon-url` <img>
+  // fallback. Rendered only when one of the two is provided, so the header has
+  // no phantom gap otherwise.
+  if (options.host.querySelector('[slot="icon"]') !== null || options.iconUrl !== null) {
+    header.append(iconElement("icon", "icon", null, options.iconUrl));
+  }
+
+  // A coarse slot for host-provided header actions, between title and controls.
+  const headerActions = document.createElement("slot");
+  headerActions.name = "header-actions";
+
+  const controls = document.createElement("div");
+  controls.className = "header-controls";
+  controls.setAttribute("part", "header-controls");
+
+  const history = headerButton("history", strings.chatHistory, "☰");
+  history.addEventListener("click", options.onHistory);
+
+  // ↺ rather than ⭯: the same idea in a glyph that has a font behind it in
+  // every browser. The obscure one rendered as an unreadable mark at 14px, and a
+  // header control nobody can name is one nobody presses.
+  const checkpoints = headerButton("checkpoints", strings.checkpoints, "↺");
+  checkpoints.addEventListener("click", options.onCheckpoints);
+
+  const newChat = headerButton("new", strings.newChat, "✚");
+  newChat.addEventListener("click", options.onNewChat);
+
+  const collapse = headerButton("collapse", strings.collapse, "—");
+  collapse.addEventListener("click", options.onCollapse);
+
+  // Only offered when the server actually indexes runs — without
+  // `data-runs-url` there is nothing to continue and the button would open
+  // a permanently empty panel.
+  if (options.withCheckpoints) {
+    controls.append(history, checkpoints, newChat);
+  } else {
+    controls.append(history, newChat);
+  }
+  // Optional built-in theme toggle: off unless the host opts in, so
+  // it never competes with a host-supplied switch in `slot="header-actions"`.
+  const toggle = options.themeToggle;
+  if (toggle !== null) {
+    toggle.type = "button";
+    toggle.className = "header-btn header-btn--theme";
+    toggle.setAttribute("part", "header-button theme-toggle");
+    toggle.title = strings.toggleTheme;
+    toggle.setAttribute("aria-label", strings.toggleTheme);
+    toggle.addEventListener("click", options.onToggleTheme, { signal: options.signal });
+    controls.append(toggle);
+  }
+  controls.append(collapse);
+  header.append(title, headerActions, controls);
+  return { header, checkpoints };
+}

package/src/ui/shell/build_launcher.ts

@@ -0,0 +1,50 @@
+import { ICON_LAUNCHER } from "../../constants.js";
+import type { UiStrings } from "../ui_strings.js";
+import { iconElement } from "./icon_element.js";
+
+/** The launcher's parts, owned by the element, and what fills them. */
+export interface LauncherOptions {
+  readonly launcher: HTMLButtonElement;
+  readonly badge: HTMLElement;
+  readonly railLabel: HTMLElement;
+  readonly titleText: string;
+  readonly iconUrl: string | null;
+  readonly strings: UiStrings;
+  readonly signal: AbortSignal;
+  readonly onOpen: () => void;
+}
+
+/**
+ * Build what a collapsed widget shrinks to: a round floating button, or the
+ * slim edge rail under `placement="sidebar"` -- one element, shaped by the
+ * stylesheet. The element mounts it as a sibling of the panel, so it survives
+ * the panel being hidden.
+ */
+export function buildLauncher(options: LauncherOptions): void {
+  const { launcher, badge, railLabel } = options;
+  launcher.className = "launcher";
+  launcher.type = "button";
+  launcher.setAttribute("part", "launcher");
+  launcher.setAttribute("aria-label", options.strings.expand);
+  badge.className = "launcher-badge";
+  badge.setAttribute("part", "launcher-badge");
+  // The count is announced through the launcher's own label, so the badge is
+  // decoration to a screen reader rather than a second, context-free number.
+  badge.setAttribute("aria-hidden", "true");
+  badge.hidden = true;
+  // Only the edge rail shows this. A full-height column carrying one small
+  // icon reads as a coloured stripe rather than a way back into a
+  // conversation -- it is the widest collapsed state there is and the one
+  // that says least about itself. Written here and hidden in CSS everywhere
+  // else, because the launcher is one element shaped by placement.
+  railLabel.className = "rail-label";
+  railLabel.setAttribute("part", "rail-label");
+  railLabel.setAttribute("aria-hidden", "true");
+  railLabel.textContent = options.titleText;
+  launcher.replaceChildren(
+    iconElement("launcher", "launcher-icon", ICON_LAUNCHER, options.iconUrl),
+    railLabel,
+    badge,
+  );
+  launcher.addEventListener("click", options.onOpen, { signal: options.signal });
+}