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

package/src/core/read_flag.ts

@@ -0,0 +1,13 @@
+/**
+ * Read an opt-in flag attribute on `element` the way HTML reads a boolean
+ * attribute.
+ *
+ * Present means on: bare (`data-prompt-chips`), empty (`=""`), or any value
+ * except the literal `"false"`. Comparing against `"true"` instead would make
+ * the bare spelling every native boolean attribute uses silently disable the
+ * feature it names. `="false"` still turns it off.
+ */
+export function readFlag(element: Element, name: string): boolean {
+  const value = element.getAttribute(name);
+  return value !== null && value !== "false";
+}

package/src/core/read_json_attribute.ts

@@ -0,0 +1,30 @@
+/**
+ * Parse a JSON-valued attribute on `element`, saying so when it will not parse.
+ *
+ * `null` for an absent attribute, and `null` again for one that is not JSON --
+ * but not quietly the second time. Quoting JSON inside an HTML attribute is
+ * fiddly, and the result of getting it wrong is indistinguishable from the
+ * feature being switched off: no chips appear, or the strings stay English,
+ * with nothing anywhere saying why. That is the same failure `data-paste-attach`
+ * already reports for a value it cannot read.
+ *
+ * Console only. A page author's typo is not the reader's business, nothing the
+ * reader did was refused, and the degraded widget is still perfectly usable.
+ */
+export function readJsonAttribute(element: Element, name: string): unknown {
+  const raw = element.getAttribute(name);
+  if (raw === null) {
+    return null;
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    console.warn(
+      `<ag-ui-chat>: ${name} is not valid JSON, so it was ignored entirely and ` +
+        "the built-in default is being used. Check the quoting -- JSON inside " +
+        "an HTML attribute needs single quotes around the attribute value, or " +
+        "its own double quotes escaped.",
+    );
+    return null;
+  }
+}

package/src/tools/tool_catalog.ts

@@ -36,6 +36,11 @@ export interface ToolCatalogHost {
   readonly askUserRenderer: () => QuestionRenderer | null;
   /** The decision a run is suspended on, which a Stop abandons. */
   readonly decision: PendingDecision;
+  /**
+   * Mark the card of ``callId`` as asking the user, or no longer. The call id is
+   * absent for a handler run outside a tool call, which has no card to mark.
+   */
+  readonly setAsking: (callId: string | undefined, asking: boolean) => void;
   /** The current answer group, opening one if none is open. */
   readonly ensureGroup: () => HTMLDivElement;
   /** The resolved string table. */
@@ -293,17 +298,25 @@ export class ToolCatalog {
     // A host-supplied renderer takes full control of the UI.
     const renderer = this.#host.askUserRenderer();
     let answer: string;
-    if (renderer === null) {
-      answer = await builtIn();
-    } else {
-      // Awaited here rather than inside a helper, so an answering renderer
-      // takes exactly as many turns to be heard as it always did.
-      try {
-        // Called on the element, as `this.askUserRenderer(...)` always was.
-        answer = await renderer.call(this.#host.element, request, { signal });
-      } catch (error) {
-        answer = await this.#afterRendererFailed(error, signal, callId, builtIn);
+    // The card says it is asking for as long as a question is open on it, an
+    // answer, a Stop and a renderer that failed alike, so the step group's row
+    // does not read as running while the run waits on a person.
+    this.#host.setAsking(callId, true);
+    try {
+      if (renderer === null) {
+        answer = await builtIn();
+      } else {
+        // Awaited here rather than inside a helper, so an answering renderer
+        // takes exactly as many turns to be heard as it always did.
+        try {
+          // Called on the element, as `this.askUserRenderer(...)` always was.
+          answer = await renderer.call(this.#host.element, request, { signal });
+        } catch (error) {
+          answer = await this.#afterRendererFailed(error, signal, callId, builtIn);
+        }
       }
+    } finally {
+      this.#host.setAsking(callId, false);
     }
     this.#host.decision.close();
     this.#host.updateEmptyState();

package/src/tools/tool_dispatch.ts

@@ -166,6 +166,7 @@ export class ToolDispatch {
     // transcript places itself against its own card, and by the time it runs the
     // card is no longer reachable by id.
     this.#host.transcript.setCardElement(call.id, card.element);
+    this.#host.transcript.holdRunning(call.id, card);
     // Scoped out of this round's catalog ⇒ not a frontend tool of ours, for
     // this round. A host that offers `delete_record` only on the page where
     // deleting makes sense has said something about *this* run, and a call
@@ -254,17 +255,26 @@ export class ToolDispatch {
       // to the message list made it a sibling *after* the group, so anything
       // that streamed afterwards rendered above it and the prompt drifted to
       // the foot of the turn no matter when it was asked.
-      const decision = requestConfirmation(this.#host.transcript.ensureGroup(), request, {
-        signal,
-        strings: this.#host.strings(),
-        // Offered only where it can be honoured -- see `#confirmationRule`.
-        ...(rule === "destructive"
-          ? { onAlwaysAllow: () => this.#sessionApproved.add(call.name) }
-          : {}),
-      });
-      this.#host.transcript.updateEmptyState();
-      this.#host.transcript.follow();
-      const accepted = await decision;
+      //
+      // The card says it is asking for as long as the prompt is open, however it
+      // ends, so a step group's row reads "waiting for you" rather than running.
+      card.setAsking(true);
+      let accepted: boolean;
+      try {
+        const decision = requestConfirmation(this.#host.transcript.ensureGroup(), request, {
+          signal,
+          strings: this.#host.strings(),
+          // Offered only where it can be honoured -- see `#confirmationRule`.
+          ...(rule === "destructive"
+            ? { onAlwaysAllow: () => this.#sessionApproved.add(call.name) }
+            : {}),
+        });
+        this.#host.transcript.updateEmptyState();
+        this.#host.transcript.follow();
+        accepted = await decision;
+      } finally {
+        card.setAsking(false);
+      }
       this.#host.decision.close();
       // A handover while the card was open declines it, as any Stop does, but
       // the transcript the decline would be drawn into is the next principal's
@@ -458,6 +468,11 @@ export class ToolDispatch {
           request.args = card.args;
         }
         card?.mark(TOOL_CALL_STATUS.DEFERRED);
+        // Before either renderer runs: the built-in card focuses its approve
+        // button as it is drawn, and a folded step group has no box to focus in.
+        if (card !== undefined) {
+          this.#host.transcript.revealStep(card);
+        }
         // The built-in card renders into the gated call's own card, falling back
         // to the answer group when the interrupt names no call we hold one for.
         const builtIn = (): Promise<boolean> =>

package/src/ui/charts/chart_block.ts

@@ -96,16 +96,16 @@ const WIDTH_STEP = 8;
 /** A rough advance width per character for the 10px axis font. */
 const AXIS_CHAR_WIDTH = 5.6;
 
-// Read from the host's own palette rather than a fixed ramp: the component
-// themes through custom properties everywhere else, and a chart that ignored
-// that would be the one element a host could not restyle.
+// Read from the theme's palette rather than a fixed ramp. The private alias
+// reads the host's --ag-ui-chart-N first (see token_styles), so a host's
+// colour wins over any theme's, and a theme can still supply its own.
 const SERIES_COLORS: readonly string[] = [
-  "var(--ag-ui-chart-1, #4f7cff)",
-  "var(--ag-ui-chart-2, #21b573)",
-  "var(--ag-ui-chart-3, #e0803c)",
-  "var(--ag-ui-chart-4, #b563d8)",
-  "var(--ag-ui-chart-5, #d84f6e)",
-  "var(--ag-ui-chart-6, #3ba7c4)",
+  "var(--_chart-1)",
+  "var(--_chart-2)",
+  "var(--_chart-3)",
+  "var(--_chart-4)",
+  "var(--_chart-5)",
+  "var(--_chart-6)",
 ];
 
 /** The colour for series `index`, wrapping when there are more series than colours. */

package/src/ui/charts/chart_styles.ts

@@ -0,0 +1,63 @@
+// Charts drawn in the transcript: the block, its title and legend.
+export const CHART_STYLES: string = `
+/* Charts.
+ *
+ * The SVG scales to the column and carries no colours of its own beyond the
+ * series palette, so a host restyles it the same way it restyles everything
+ * else. Series colours are custom properties with fallbacks rather than fixed
+ * values, and the axis furniture inherits currentColor at low opacity so it
+ * reads correctly in either theme without a second palette.
+ */
+/* A chart is sized like a message, not like a panel: it takes the width it
+   needs and stops, rather than stretching into whatever room the transcript
+   has. A message bubble caps at 80% for the same reason -- widening the panel
+   should not resize what is already in it. The cap is a token so a host with a
+   wide panel and a real reason can raise it; the default is the width this
+   renderer has always drawn at. Below the cap the block still fills its column,
+   which is what a narrow panel needs. */
+.chart-block {
+  align-self: flex-start;
+  width: 100%;
+  max-width: var(--_chart-max-width);
+  margin: 6px 0;
+  color: var(--_fg);
+}
+
+/* The drawing fills the block's width and carries its own height in the
+   viewBox, so it is laid out rather than magnified: block display keeps the
+   inline baseline gap from adding a stripe under every chart. */
+.chart-block svg {
+  display: block;
+  width: 100%;
+  height: auto;
+}
+
+.chart-title {
+  margin-bottom: 2px;
+  font-size: 0.85em;
+  font-weight: 600;
+  opacity: 0.85;
+}
+
+.chart-legend {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 4px 12px;
+  margin-top: 4px;
+  font-size: 0.78em;
+  opacity: 0.75;
+}
+
+.chart-legend-item {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+}
+
+.chart-legend-swatch {
+  width: 9px;
+  height: 9px;
+  border-radius: 2px;
+  flex: 0 0 auto;
+}
+`;

package/src/ui/composer/attachment_styles.ts

@@ -0,0 +1,71 @@
+// The composer's attachment picker, voice button and attachment tray.
+export const ATTACHMENT_STYLES: string = `
+/* ── File attachments ───────────────────────────────────────────────────── */
+/* The picker button sits in the composer's tool row; hidden until
+   data-attachments-url. */
+.attach-input {
+  display: none;
+}
+
+/* The mic button's mount point; filled only once ComposerVoice.wire mounts
+   the control, which it skips unless transcription is configured. */
+.voice-slot {
+  display: contents;
+}
+
+/* Recording: a red tint + a gentle pulse so it's clearly "live". */
+.voice-btn[data-state="recording"] {
+  background: var(--_danger);
+  color: var(--_on-danger);
+  animation: ag-ui-voice-pulse 1.2s ease-in-out infinite;
+}
+
+.voice-btn[data-state="recording"]:hover {
+  background: var(--_danger);
+  color: var(--_on-danger);
+}
+
+@keyframes ag-ui-voice-pulse {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.6; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .voice-btn[data-state="recording"] {
+    animation: none;
+  }
+}
+
+/* Pending-attachments tray, above the input row; collapses (hidden) when empty. */
+.attachment-slot {
+  display: contents;
+}
+
+/* The padding is the only separation the tray gets: its slot is display:
+   contents, so the tray is a direct child of the .chat column, and that column
+   sets no gap. The bottom value keeps a chip off the composer's top edge.
+   The inline value here is only the default: the page placement overrides
+   padding-inline further down to compute its reading-column gutter, and wins
+   on specificity whichever way this declaration is written. Read the two
+   together before changing either. */
+.attachment-tray {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  padding: 8px 12px;
+}
+
+/* The tray sets the hidden property while empty, and an author display beats
+   the UA stylesheet's rule for it, so without this the empty tray keeps
+   laying out and its padding is permanent dead space above the composer. */
+.attachment-tray[hidden] {
+  display: none;
+}
+
+.attachment-chips {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  margin-top: 6px;
+}
+`;

package/src/ui/composer/build_composer.ts

@@ -0,0 +1,112 @@
+import { ICON_ATTACH, ICON_SEND, ICON_STOP } from "../../constants.js";
+import { glyphSlot } from "../shell/glyph_slot.js";
+import type { UiStrings } from "../ui_strings.js";
+
+/** The composer's parts, owned by the element, and what they call back into. */
+export interface ComposerOptions {
+  readonly input: HTMLTextAreaElement;
+  readonly send: HTMLButtonElement;
+  readonly attachButton: HTMLButtonElement;
+  readonly fileInput: HTMLInputElement;
+  readonly voiceSlot: HTMLElement;
+  /** The line saying what the composer still needs; sits above the input. */
+  readonly hint: HTMLElement;
+  /** The queued-message row; sits above the input beside the tray. */
+  readonly queuedRow: HTMLElement;
+  /** Where the attachment tray mounts; sits above the input. */
+  readonly attachSlot: HTMLElement;
+  readonly strings: UiStrings;
+  readonly signal: AbortSignal;
+  readonly onKeydown: (event: KeyboardEvent) => void;
+  readonly onInput: () => void;
+  /** Send while idle, Stop while a run is in flight: the element decides. */
+  readonly onSend: () => void;
+  readonly onFilesPicked: () => void;
+}
+
+/**
+ * Build the composer row -- the field, and the tool row under it with the
+ * attach, voice and send controls -- and ready the composer surfaces the
+ * element mounts above it: the hint, the queued row and the attachment slot.
+ * Returns the row; the element places it and the surfaces.
+ */
+export function buildComposer(options: ComposerOptions): HTMLElement {
+  const { input, send, attachButton, fileInput, strings, signal } = options;
+
+  const queued = options.queuedRow;
+  queued.className = "queued";
+  queued.setAttribute("part", "queued");
+  queued.setAttribute("role", "group");
+  queued.setAttribute("aria-label", strings.queued);
+  queued.hidden = true;
+
+  const inputRow = document.createElement("div");
+  inputRow.className = "input-row";
+  inputRow.setAttribute("part", "composer");
+
+  // One bordered surface holds the field and the tool row under it, so the
+  // icon buttons stop competing with the field for weight.
+  const composer = document.createElement("div");
+  composer.className = "composer";
+  composer.setAttribute("part", "composer-surface");
+
+  const tools = document.createElement("div");
+  tools.className = "composer-tools";
+  tools.setAttribute("part", "composer-tools");
+
+  input.className = "input";
+  input.setAttribute("part", "input");
+  input.setAttribute("aria-label", strings.message);
+  input.rows = 1;
+  input.placeholder = strings.inputPlaceholder;
+  input.addEventListener("keydown", options.onKeydown, { signal });
+  input.addEventListener("input", options.onInput, { signal });
+
+  // Icon-only, with both glyphs mounted at once and CSS showing the one the
+  // state calls for — swapping a single glyph would leave a host that slotted
+  // its own Send mark holding a stop icon mid-run.
+  send.className = "send";
+  send.type = "button";
+  send.setAttribute("part", "send");
+  send.replaceChildren(
+    glyphSlot("icon-send", "send-send", ICON_SEND),
+    glyphSlot("icon-stop", "send-stop", ICON_STOP),
+  );
+  send.title = strings.send;
+  send.setAttribute("aria-label", strings.send);
+  send.dataset["state"] = "idle";
+  send.addEventListener("click", options.onSend, { signal });
+
+  const hint = options.hint;
+  hint.className = "skill-hint";
+  hint.setAttribute("part", "skill-hint");
+  hint.hidden = true;
+
+  // File-upload affordance: a paperclip button (hidden until
+  // `data-attachments-url` is wired) opening a hidden multi-file input.
+  // Drag-and-drop covers the whole shell (wired by ComposerAttachments).
+  attachButton.className = "attach-btn";
+  attachButton.type = "button";
+  attachButton.setAttribute("part", "attach-button");
+  attachButton.replaceChildren(glyphSlot("icon-attach", "attach-glyph", ICON_ATTACH));
+  attachButton.title = strings.attachFiles;
+  attachButton.setAttribute("aria-label", strings.attachFiles);
+  attachButton.hidden = true;
+  attachButton.addEventListener("click", () => fileInput.click(), { signal });
+
+  fileInput.className = "attach-input";
+  fileInput.type = "file";
+  fileInput.multiple = true;
+  fileInput.hidden = true;
+  fileInput.addEventListener("change", options.onFilesPicked, { signal });
+
+  options.attachSlot.className = "attachment-slot";
+
+  // Mic button mount point (kept empty until ComposerVoice mounts the control).
+  options.voiceSlot.className = "voice-slot";
+
+  tools.append(attachButton, options.voiceSlot, send);
+  composer.append(input, tools);
+  inputRow.append(composer, fileInput);
+  return inputRow;
+}

package/src/ui/composer/composer_styles.ts

@@ -0,0 +1,174 @@
+// The composer: field, tool row, icon buttons, send and stop, and the glyph
+// class every icon button and icon holder paints with.
+export const COMPOSER_STYLES: string = `
+/* ── Composer ───────────────────────────────────────────────────────────────
+   One surface owns the border, the background and the focus ring; the field
+   and its tool row sit inside it, rather than being siblings stretched to the
+   textarea's height. */
+.input-row {
+  display: flex;
+  padding: 12px;
+  border-top: 1px solid var(--_border);
+}
+
+.composer {
+  flex: 1;
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding: 6px 6px 6px 10px;
+  background: var(--_input-bg);
+  border: 1px solid var(--_border);
+  border-radius: var(--_composer-radius);
+  transition: border-color var(--_motion) var(--_ease);
+}
+
+.composer:focus-within {
+  border-color: var(--_accent);
+}
+
+/* The field grows with its content (sized by #autoGrow) up to the ceiling,
+   then scrolls. border-box keeps that measurement stable: with content-box the
+   padding would be added to every scrollHeight read and the field would creep
+   taller on each keystroke. */
+.input {
+  box-sizing: border-box;
+  resize: none;
+  max-height: var(--_composer-max-height);
+  overflow-y: auto;
+  /* Scrolling past the end of this must not scroll the page behind it. */
+  overscroll-behavior: contain;
+  padding: 6px 4px 2px;
+  background: transparent;
+  border: none;
+  font: inherit;
+  color: inherit;
+  outline: none;
+}
+
+.composer-tools {
+  display: flex;
+  align-items: center;
+  gap: 2px;
+}
+
+/* Icon buttons: quiet at rest, so the field is what the eye lands on. */
+.attach-btn,
+.voice-btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--_tool-btn-size);
+  height: var(--_tool-btn-size);
+  padding: 0;
+  border: none;
+  border-radius: 8px;
+  background: transparent;
+  color: var(--_muted);
+  font: inherit;
+  line-height: 1;
+  cursor: pointer;
+  transition:
+    background-color var(--_motion) var(--_ease),
+    color var(--_motion) var(--_ease);
+}
+
+.attach-btn:hover,
+.voice-btn:hover {
+  background: var(--_hover);
+  color: var(--_fg);
+}
+
+.attach-btn:disabled,
+.voice-btn:disabled {
+  cursor: default;
+  opacity: 0.6;
+}
+
+/* The same trap the attachment tray carries a note about, two rules along: an
+   author display beats the UA stylesheet's rule for the hidden property, so a
+   button the element has explicitly hidden keeps laying out and painting. The
+   clip is hidden until a host supplies an upload handler or an attachments URL,
+   and without this it is a visible control that cannot do anything.
+
+   The mic needs no such rule, and the asymmetry is worth knowing before adding
+   one: it is not hidden when unconfigured, it is never built. The voice wiring
+   returns before constructing the button, leaving only an empty voice slot that
+   is display: contents. A hidden-state rule for the mic would match nothing. */
+.attach-btn[hidden] {
+  display: none;
+}
+
+/* Send closes the row on the right: a circle, the only filled control in the
+   composer, so "the thing that acts" reads at a glance. */
+.send {
+  margin-left: auto;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: none;
+  width: var(--_send-size);
+  height: var(--_send-size);
+  padding: 0;
+  border: none;
+  border-radius: 50%;
+  background: var(--_accent);
+  color: var(--_on-accent);
+  font: inherit;
+  line-height: 1;
+  cursor: pointer;
+  transition:
+    background-color var(--_motion) var(--_ease),
+    transform var(--_motion) var(--_ease-pop);
+}
+
+.send:hover {
+  transform: scale(1.08);
+}
+
+.send:active {
+  transform: scale(0.92);
+}
+
+.send:disabled {
+  opacity: 0.5;
+  cursor: default;
+  transform: none;
+}
+
+/* The composer button doubles as the Stop control while a run is in flight —
+   same circle, different glyph, so nothing moves when a run starts. */
+.send[data-state="running"] {
+  background: var(--_muted);
+}
+
+.send[data-state="idle"] .send-stop,
+.send[data-state="running"] .send-send {
+  display: none;
+}
+
+/* Glyphs — one class, painted from the button's own colour so every state
+   (hover, recording, running) carries the icon with it. */
+.glyph {
+  width: var(--_glyph-size);
+  height: var(--_glyph-size);
+  fill: none;
+  stroke: currentColor;
+  stroke-width: var(--_glyph-stroke);
+  stroke-linecap: round;
+  stroke-linejoin: round;
+}
+
+.glyph--solid {
+  fill: currentColor;
+  stroke: none;
+}
+
+/* In an icon holder (header brand, launcher) the glyph takes the holder's size
+   rather than the composer's. */
+.icon-holder .glyph {
+  width: 100%;
+  height: 100%;
+}
+`;