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

package/src/ui/charts/chart_tool.ts

@@ -0,0 +1,72 @@
+/**
+ * The built-in `render_chart` tool: the agent-called route to a chart.
+ *
+ * A thin thing on purpose. It carries no `handler` of its own beyond reporting
+ * back to the model, because everything it does is drawing — which lives in
+ * `render`, the half the component replays. A consumer wanting charts gets this
+ * without writing a renderer; a consumer wanting something else writes their own
+ * tool against the same seam.
+ */
+
+import type { ClientTool } from "../../tools/client_tool_registry.js";
+import { renderChart } from "./chart_block.js";
+import { chartSpecFrom } from "./chart_spec_from.js";
+
+/** The name the built-in chart tool registers under. */
+export const CHART_TOOL_NAME = "render_chart";
+
+function draw(args: Record<string, unknown>): HTMLDivElement | null {
+  const spec = chartSpecFrom(args);
+  return spec === null ? null : renderChart(spec);
+}
+
+/** Whether these arguments would produce a chart, without producing one. */
+function drawable(args: Record<string, unknown>): boolean {
+  const spec = chartSpecFrom(args);
+  return spec !== null && spec.labels.length > 0 && spec.series.length > 0;
+}
+
+const REJECTED =
+  "chart not rendered: expected labels (strings) and series, each with one finite number per label";
+
+/** The built-in chart tool. */
+export function createChartTool(): ClientTool {
+  return {
+    name: CHART_TOOL_NAME,
+    description:
+      "Show a chart in the conversation. Supply the data and the page draws it. " +
+      "Every series must have exactly one point per label.",
+    parameters: {
+      type: "object",
+      properties: {
+        kind: { type: "string", enum: ["bar", "line", "pie", "scatter", "stacked"] },
+        title: { type: "string" },
+        labels: { type: "array", items: { type: "string" } },
+        series: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              label: { type: "string" },
+              points: { type: "array", items: { type: "number" } },
+            },
+            required: ["points"],
+          },
+        },
+      },
+      required: ["labels", "series"],
+      "x-summary": "Draw a chart",
+    },
+    // Says what happened and nothing else; the drawing is `render`'s job. Told
+    // plainly when the arguments are unusable, because the model can fix that
+    // and retry — a silent no-op would leave it believing the chart is on screen.
+    // Answers on what will actually be drawn, not on what validated: a spec can
+    // pass validation and still have nothing to show, and reporting success
+    // then would leave the model believing a chart is on screen. Asks the
+    // question without building the chart, because `render` is about to build
+    // the same one a moment later and drawing it twice is pure waste on a spec
+    // large enough to matter.
+    handler: (args: Record<string, unknown>) => (drawable(args) ? "chart rendered" : REJECTED),
+    render: draw,
+  };
+}

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

@@ -0,0 +1,295 @@
+import { randomUUID } from "@ag-ui/client";
+import { ATTACHMENT_STATUS } from "../../constants.js";
+import type { AttachmentRef } from "../../core/attachment.js";
+import type { UploadHandler } from "../../core/upload_attachment.js";
+import { commaTokens } from "../../core/utils.js";
+import { fillUiString } from "../fill_ui_string.js";
+import { formatBytes, iconFor } from "../transcript/attachment_chips.js";
+import { DEFAULT_UI_STRINGS, type UiStrings } from "../ui_strings.js";
+
+/** Status of a pending tray chip. */
+type AttachmentStatus = (typeof ATTACHMENT_STATUS)[keyof typeof ATTACHMENT_STATUS];
+
+/** Config the host ({@link AgUiChat}) hands the tray. */
+export interface AttachmentTrayConfig {
+  /** Upload one file, reporting `0..1` progress; resolves to a durable ref. */
+  readonly upload: UploadHandler;
+  /** Client-side size cap in bytes (`0` = no cap). The server stays authoritative. */
+  readonly maxBytes: number;
+  /** Client-side accept list (`<input accept>` syntax; `""` = any). */
+  readonly accept: string;
+  /** Fired when the set of attachments changes (add / settle / remove). */
+  readonly onChange?: () => void;
+  /** Localized strings; defaults to the English {@link DEFAULT_UI_STRINGS}. */
+  readonly strings?: UiStrings;
+}
+
+/** One pending file in the tray, from pick to ready/error. */
+interface TrayItem {
+  readonly localId: string;
+  readonly file: File;
+  status: AttachmentStatus;
+  progress: number;
+  ref: AttachmentRef | null;
+  error: string;
+  /** Aborts the in-flight upload when the chip is removed / the tray cleared. */
+  controller: AbortController | null;
+}
+
+/**
+ * The composer's pending-attachments tray: a chip per picked file with a
+ * progress bar while it uploads, settling to a ready chip holding the durable
+ * ref or an error chip with retry. A stateful view like {@link ThreadDrawer}:
+ * the host appends {@link element}, calls {@link add} on pick or drop, reads
+ * {@link readyRefs} on send, and clears it.
+ *
+ * Client-side size and type guards reject a bad file into an error chip without
+ * uploading, for instant feedback, but the server stays the authority.
+ */
+export class AttachmentTray {
+  /** The tray root; append above the input row. Hidden while empty. */
+  readonly element: HTMLDivElement;
+
+  readonly #config: AttachmentTrayConfig;
+  readonly #strings: UiStrings;
+  #items: TrayItem[] = [];
+
+  constructor(config: AttachmentTrayConfig) {
+    this.#config = config;
+    this.#strings = config.strings ?? DEFAULT_UI_STRINGS;
+    this.element = document.createElement("div");
+    this.element.className = "attachment-tray";
+    this.element.setAttribute("part", "attachment-tray");
+    this.element.hidden = true;
+  }
+
+  /** Queue a file: reject oversize/disallowed into an error chip, else upload. */
+  add(file: File): void {
+    const item: TrayItem = {
+      localId: randomUUID(),
+      file,
+      status: ATTACHMENT_STATUS.UPLOADING,
+      progress: 0,
+      ref: null,
+      error: "",
+      controller: null,
+    };
+    this.#items.push(item);
+    const rejection = this.#reject(file);
+    if (rejection !== null) {
+      item.status = ATTACHMENT_STATUS.ERROR;
+      item.error = rejection;
+      this.#render();
+      this.#config.onChange?.();
+      return;
+    }
+    this.#render();
+    this.#config.onChange?.();
+    this.#upload(item);
+  }
+
+  /** The durable refs of every chip that finished uploading. */
+  readyRefs(): readonly AttachmentRef[] {
+    const refs: AttachmentRef[] = [];
+    for (const item of this.#items) {
+      if (item.ref !== null) {
+        refs.push(item.ref);
+      }
+    }
+    return refs;
+  }
+
+  /** Whether any chip is still uploading (a send would drop nothing if false). */
+  hasPending(): boolean {
+    return this.#items.some((item) => item.status === ATTACHMENT_STATUS.UPLOADING);
+  }
+
+  /** How many chips are still uploading — the count a send-time notice names. */
+  pendingCount(): number {
+    return this.#items.filter((item) => item.status === ATTACHMENT_STATUS.UPLOADING).length;
+  }
+
+  /** Whether the tray holds no chips. */
+  isEmpty(): boolean {
+    return this.#items.length === 0;
+  }
+
+  /** Drop the settled (ready / error) chips, leaving any still uploading. */
+  clearReady(): void {
+    this.#items = this.#items.filter((item) => item.status === ATTACHMENT_STATUS.UPLOADING);
+    this.#render();
+  }
+
+  /** Drop every chip (a reset / new-chat), aborting any in-flight upload. */
+  clear(): void {
+    for (const item of this.#items) {
+      item.controller?.abort();
+    }
+    this.#items = [];
+    this.#render();
+  }
+
+  /**
+   * Abort every in-flight upload without touching the rendered chips — the
+   * teardown path when the host element is removed mid-upload, so a cancelled
+   * transfer doesn't orphan a server-side file.
+   */
+  dispose(): void {
+    for (const item of this.#items) {
+      item.controller?.abort();
+    }
+  }
+
+  /** The size/type rejection reason for a file, or `null` when accepted. */
+  #reject(file: File): string | null {
+    if (this.#config.maxBytes > 0 && file.size > this.#config.maxBytes) {
+      return fillUiString(this.#strings.tooLarge, { size: formatBytes(this.#config.maxBytes) });
+    }
+    if (!accepts(this.#config.accept, file)) {
+      return this.#strings.fileTypeNotAllowed;
+    }
+    return null;
+  }
+
+  #upload(item: TrayItem): void {
+    // Re-apply the client guard on every attempt, not just the first `add` — an
+    // ERROR chip always renders retry, so without this a size/type-rejected file
+    // would upload in full on ↻.
+    const rejection = this.#reject(item.file);
+    if (rejection !== null) {
+      item.status = ATTACHMENT_STATUS.ERROR;
+      item.error = rejection;
+      this.#render();
+      this.#config.onChange?.();
+      return;
+    }
+    item.status = ATTACHMENT_STATUS.UPLOADING;
+    item.progress = 0;
+    item.error = "";
+    const controller = new AbortController();
+    item.controller = controller;
+    this.#render();
+    this.#config
+      .upload(
+        item.file,
+        (fraction) => {
+          item.progress = fraction;
+          this.#render();
+        },
+        controller.signal,
+      )
+      .then((ref) => {
+        item.status = ATTACHMENT_STATUS.READY;
+        item.ref = ref;
+      })
+      .catch((error: unknown) => {
+        item.status = ATTACHMENT_STATUS.ERROR;
+        item.error = error instanceof Error ? error.message : this.#strings.uploadFailed;
+      })
+      .finally(() => {
+        item.controller = null;
+        this.#render();
+        this.#config.onChange?.();
+      });
+  }
+
+  #remove(item: TrayItem): void {
+    // Abort an in-flight upload so removing its chip doesn't orphan the file.
+    item.controller?.abort();
+    this.#items = this.#items.filter((other) => other !== item);
+    this.#render();
+    this.#config.onChange?.();
+  }
+
+  #render(): void {
+    this.element.replaceChildren();
+    this.element.hidden = this.#items.length === 0;
+    for (const item of this.#items) {
+      this.element.appendChild(this.#renderChip(item));
+    }
+  }
+
+  #renderChip(item: TrayItem): HTMLDivElement {
+    const chip = document.createElement("div");
+    chip.className = `attachment-chip attachment-chip--${item.status}`;
+    chip.setAttribute("part", "attachment-chip");
+
+    const icon = document.createElement("span");
+    icon.className = "attachment-chip-icon";
+    icon.setAttribute("part", "attachment-chip-icon");
+    // Author-written glyph markup, selected by MIME family — see iconFor.
+    icon.innerHTML = iconFor(item.file.type);
+    icon.setAttribute("aria-hidden", "true");
+
+    const name = document.createElement("span");
+    name.className = "attachment-chip-name";
+    name.setAttribute("part", "attachment-chip-name");
+    name.textContent = item.file.name;
+    name.title = item.file.name;
+
+    const meta = document.createElement("span");
+    meta.className = "attachment-chip-size";
+    meta.setAttribute("part", "attachment-chip-size");
+    meta.textContent =
+      item.status === ATTACHMENT_STATUS.ERROR ? item.error : formatBytes(item.file.size);
+
+    chip.append(icon, name, meta);
+
+    if (item.status === ATTACHMENT_STATUS.UPLOADING) {
+      const bar = document.createElement("div");
+      bar.className = "attachment-chip-bar";
+      bar.setAttribute("part", "attachment-chip-bar");
+      const fill = document.createElement("div");
+      fill.className = "attachment-chip-bar-fill";
+      fill.setAttribute("part", "attachment-chip-bar-fill");
+      fill.style.width = `${Math.round(item.progress * 100)}%`;
+      bar.appendChild(fill);
+      chip.appendChild(bar);
+    }
+
+    if (item.status === ATTACHMENT_STATUS.ERROR) {
+      const retry = document.createElement("button");
+      retry.type = "button";
+      retry.className = "attachment-chip-retry";
+      retry.setAttribute("part", "attachment-chip-retry");
+      retry.title = this.#strings.retry;
+      retry.setAttribute("aria-label", this.#strings.retryUpload);
+      retry.textContent = "↻";
+      retry.addEventListener("click", () => this.#upload(item));
+      chip.appendChild(retry);
+    }
+
+    const remove = document.createElement("button");
+    remove.type = "button";
+    remove.className = "attachment-chip-remove";
+    remove.setAttribute("part", "attachment-chip-remove");
+    remove.title = this.#strings.remove;
+    remove.setAttribute("aria-label", this.#strings.removeAttachment);
+    remove.textContent = "✕";
+    remove.addEventListener("click", () => this.#remove(item));
+    chip.appendChild(remove);
+
+    return chip;
+  }
+}
+
+/** Whether `file` matches an `<input accept>` list (`""` accepts anything). */
+function accepts(accept: string, file: File): boolean {
+  // Lower-cased after the shared split rather than before the filter: no
+  // non-empty token lower-cases to an empty one, so the order cannot matter.
+  const tokens = commaTokens(accept).map((token) => token.toLowerCase());
+  if (tokens.length === 0) {
+    return true;
+  }
+  const mime = file.type.toLowerCase();
+  const name = file.name.toLowerCase();
+  return tokens.some((token) => {
+    if (token.startsWith(".")) {
+      return name.endsWith(token);
+    }
+    if (token.endsWith("/*")) {
+      return mime.startsWith(token.slice(0, -1));
+    }
+    return mime === token;
+  });
+}

package/src/ui/composer/auto_grow.ts

@@ -0,0 +1,12 @@
+/**
+ * Size the field to its content: one row when empty, growing with what is
+ * typed until the CSS ceiling takes over and it scrolls.
+ *
+ * Resetting to `auto` first is what makes it shrink again — `scrollHeight`
+ * never reports less than the current height, so measuring without the reset
+ * would ratchet the composer taller and never back down.
+ */
+export function autoGrow(input: HTMLTextAreaElement): void {
+  input.style.height = "auto";
+  input.style.height = `${input.scrollHeight}px`;
+}

package/src/ui/composer/build_composer.ts

@@ -0,0 +1,114 @@
+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 place chip; sits in the tool row between the voice slot and Send. */
+  readonly place: 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 and voice controls, the place chip and Send -- 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, options.place, send);
+  composer.append(input, tools);
+  inputRow.append(composer, fileInput);
+  return inputRow;
+}