@artooi/ag-ui-web-component 0.5.0 → 0.6.0

package/src/core/upload_attachment.ts

@@ -0,0 +1,113 @@
+import type { AttachmentRef } from "./attachment.js";
+
+/**
+ * The composer's upload contract: take a `File`, report `0..1` progress, and
+ * resolve to a durable {@link AttachmentRef}. The built-in handler is
+ * {@link uploadAttachment} (multipart POST); a host swaps in its own — e.g. a
+ * `tus-js-client` or direct-to-S3 adapter — via `AgUiChat.uploadHandler`,
+ * **without** touching the tray, the chips, or the AG-UI wire (refs are
+ * transport-agnostic).
+ */
+export type UploadHandler = (
+  file: File,
+  onProgress: (fraction: number) => void,
+) => Promise<AttachmentRef>;
+
+/** Options for {@link uploadAttachment}. */
+export interface UploadOptions {
+  /** The attachments endpoint (`data-attachments-url`). */
+  readonly url: string;
+  /** Extra HTTP headers (CSRF / auth), read fresh per upload. */
+  readonly headers?: Record<string, string>;
+  /** Progress callback, `0..1`, fired as the body uploads. */
+  readonly onProgress?: (fraction: number) => void;
+  /** Abort signal to cancel the in-flight upload. */
+  readonly signal?: AbortSignal;
+}
+
+/**
+ * Upload one file to the attachments endpoint and resolve to its durable
+ * {@link AttachmentRef}.
+ *
+ * Uses `XMLHttpRequest` (not `fetch`) for real upload-progress events: the file
+ * is sent as multipart under the `file` field, with the element's `headers` so
+ * CSRF / auth ride along exactly like the skills/tools fetches. A non-2xx
+ * response or a network/abort error rejects, so the tray can show an error chip.
+ */
+export function uploadAttachment(file: File, options: UploadOptions): Promise<AttachmentRef> {
+  return new Promise<AttachmentRef>((resolve, reject) => {
+    const form = new FormData();
+    form.append("file", file);
+
+    const xhr = new XMLHttpRequest();
+    xhr.open("POST", options.url);
+    for (const [key, value] of Object.entries(options.headers ?? {})) {
+      xhr.setRequestHeader(key, value);
+    }
+
+    const onProgress = options.onProgress;
+    if (onProgress !== undefined) {
+      xhr.upload.addEventListener("progress", (event) => {
+        if (event.lengthComputable) {
+          onProgress(event.total === 0 ? 0 : event.loaded / event.total);
+        }
+      });
+    }
+
+    xhr.addEventListener("load", () => {
+      if (xhr.status >= 200 && xhr.status < 300) {
+        try {
+          resolve(parseRef(JSON.parse(xhr.responseText)));
+        } catch {
+          reject(new Error("upload returned an unreadable response"));
+        }
+      } else {
+        reject(new Error(errorMessage(xhr)));
+      }
+    });
+    xhr.addEventListener("error", () => reject(new Error("upload failed")));
+    xhr.addEventListener("abort", () => reject(new Error("upload cancelled")));
+
+    const signal = options.signal;
+    if (signal !== undefined) {
+      signal.addEventListener("abort", () => xhr.abort());
+    }
+
+    xhr.send(form);
+  });
+}
+
+/** Validate + narrow the server's `201` body into an {@link AttachmentRef}. */
+function parseRef(body: unknown): AttachmentRef {
+  if (typeof body !== "object" || body === null) {
+    throw new Error("not an object");
+  }
+  const o = body as Record<string, unknown>;
+  const id = o["id"];
+  const name = o["name"];
+  const mime = o["mime"];
+  const size = o["size"];
+  const url = o["url"];
+  if (
+    typeof id !== "string" ||
+    typeof name !== "string" ||
+    typeof mime !== "string" ||
+    typeof size !== "number"
+  ) {
+    throw new Error("missing fields");
+  }
+  return typeof url === "string" ? { id, name, mime, size, url } : { id, name, mime, size };
+}
+
+/** A human-readable message from a non-2xx upload response. */
+function errorMessage(xhr: XMLHttpRequest): string {
+  try {
+    const body = JSON.parse(xhr.responseText) as { error?: unknown };
+    if (typeof body.error === "string") {
+      return body.error;
+    }
+  } catch {
+    // Non-JSON error body — fall through to the status text.
+  }
+  return `upload failed (${xhr.status})`;
+}

package/src/index.ts

@@ -28,6 +28,7 @@ export {
   type ExecuteTool,
   type ToolExecution,
 } from "./core/agui_client.js";
+export { type AttachmentRef, messageAttachments } from "./core/attachment.js";
 export {
   type ClientConversationStore,
   type NavigationCheckpoint,
@@ -41,6 +42,11 @@ export {
 } from "./core/create_http_agent.js";
 export { defineAgUiChat } from "./core/define_ag_ui_chat.js";
 export { RemoteConversationStore } from "./core/remote_conversation_store.js";
+export {
+  type UploadHandler,
+  type UploadOptions,
+  uploadAttachment,
+} from "./core/upload_attachment.js";
 export {
   type FlashOptions,
   focusWithFlash,

package/src/ui/attachment_chips.ts

@@ -0,0 +1,68 @@
+import type { AttachmentRef } from "../core/attachment.js";
+
+/**
+ * Render the read-only attachment chips shown on a sent user message bubble
+ * (and on restored history) — one chip per ref with a type icon, the filename,
+ * and a human size. Static by design: no progress, no remove (that lives in the
+ * composer tray); a restored bubble re-renders these with no animation.
+ */
+export function renderAttachmentChips(refs: readonly AttachmentRef[]): HTMLDivElement {
+  const list = document.createElement("div");
+  list.className = "attachment-chips";
+  for (const ref of refs) {
+    list.appendChild(renderChip(ref));
+  }
+  return list;
+}
+
+function renderChip(ref: AttachmentRef): HTMLDivElement {
+  const chip = document.createElement("div");
+  chip.className = "attachment-chip attachment-chip--ready";
+
+  const icon = document.createElement("span");
+  icon.className = "attachment-chip-icon";
+  icon.textContent = iconFor(ref.mime);
+  icon.setAttribute("aria-hidden", "true");
+
+  const name = document.createElement("span");
+  name.className = "attachment-chip-name";
+  name.textContent = ref.name;
+  name.title = ref.name;
+
+  const size = document.createElement("span");
+  size.className = "attachment-chip-size";
+  size.textContent = formatBytes(ref.size);
+
+  chip.append(icon, name, size);
+  return chip;
+}
+
+/** A coarse type icon for a chip — image, document, or generic file. */
+export function iconFor(mime: string): string {
+  if (mime.startsWith("image/")) {
+    return "🖼";
+  }
+  if (mime === "application/pdf") {
+    return "📕";
+  }
+  if (mime.startsWith("text/")) {
+    return "📄";
+  }
+  return "📎";
+}
+
+/** A compact human-readable byte size (e.g. `1.2 MB`). */
+export function formatBytes(bytes: number): string {
+  if (bytes < 1024) {
+    return `${bytes} B`;
+  }
+  const units = ["KB", "MB", "GB"];
+  let value = bytes / 1024;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit += 1;
+  }
+  const rounded = value < 10 ? Math.round(value * 10) / 10 : Math.round(value);
+  return `${rounded} ${units[unit]}`;
+}

package/src/ui/attachment_tray.ts

@@ -0,0 +1,237 @@
+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 { formatBytes, iconFor } from "./attachment_chips.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;
+}
+
+/** 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;
+}
+
+/**
+ * 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* in the spirit of
+ * {@link ThreadDrawer} — the host appends {@link element}, calls {@link add} on
+ * pick/drop, reads {@link readyRefs} when the user sends, and clears it.
+ *
+ * Client-side size/type guards reject a bad file into an error chip without
+ * uploading — instant feedback, but the server is the authority.
+ */
+export class AttachmentTray {
+  /** The tray root; append above the input row. Hidden while empty. */
+  readonly element: HTMLDivElement;
+
+  readonly #config: AttachmentTrayConfig;
+  #items: TrayItem[] = [];
+
+  constructor(config: AttachmentTrayConfig) {
+    this.#config = config;
+    this.element = document.createElement("div");
+    this.element.className = "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: "",
+    };
+    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);
+  }
+
+  /** 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). */
+  clear(): void {
+    this.#items = [];
+    this.#render();
+  }
+
+  /** 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 `Too large (max ${formatBytes(this.#config.maxBytes)})`;
+    }
+    if (!accepts(this.#config.accept, file)) {
+      return "File type not allowed";
+    }
+    return null;
+  }
+
+  #upload(item: TrayItem): void {
+    item.status = ATTACHMENT_STATUS.UPLOADING;
+    item.progress = 0;
+    item.error = "";
+    this.#render();
+    this.#config
+      .upload(item.file, (fraction) => {
+        item.progress = fraction;
+        this.#render();
+      })
+      .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 : "upload failed";
+      })
+      .finally(() => {
+        this.#render();
+        this.#config.onChange?.();
+      });
+  }
+
+  #remove(item: TrayItem): void {
+    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}`;
+
+    const icon = document.createElement("span");
+    icon.className = "attachment-chip-icon";
+    icon.textContent = iconFor(item.file.type);
+    icon.setAttribute("aria-hidden", "true");
+
+    const name = document.createElement("span");
+    name.className = "attachment-chip-name";
+    name.textContent = item.file.name;
+    name.title = item.file.name;
+
+    const meta = document.createElement("span");
+    meta.className = "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";
+      const fill = document.createElement("div");
+      fill.className = "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.title = "Retry";
+      retry.setAttribute("aria-label", "Retry upload");
+      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.title = "Remove";
+    remove.setAttribute("aria-label", "Remove attachment");
+    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 {
+  const tokens = accept
+    .split(",")
+    .map((token) => token.trim().toLowerCase())
+    .filter((token) => token !== "");
+  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/styles.ts

@@ -506,6 +506,116 @@ export const STYLES = `
   background: var(--ag-ui-muted);
 }
 
+/* ── File attachments ───────────────────────────────────────────────────── */
+/* The 📎 picker button sits left of the input; hidden until data-attachments-url. */
+.attach-btn {
+  border: 1px solid var(--ag-ui-border);
+  border-radius: 8px;
+  padding: 0 10px;
+  background: var(--ag-ui-input-bg);
+  color: inherit;
+  font: inherit;
+  cursor: pointer;
+}
+
+.attach-btn:hover {
+  border-color: var(--ag-ui-accent);
+}
+
+.attach-input {
+  display: none;
+}
+
+/* Pending-attachments tray, above the input row; collapses (hidden) when empty. */
+.attachment-slot {
+  display: contents;
+}
+
+.attachment-tray {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  padding: 8px 12px 0;
+}
+
+.attachment-chips {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  margin-top: 6px;
+}
+
+.attachment-chip {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  max-width: 100%;
+  padding: 4px 8px;
+  border: 1px solid var(--ag-ui-border);
+  border-radius: 999px;
+  background: var(--ag-ui-assistant-bg);
+  font-size: 0.85em;
+  position: relative;
+}
+
+.attachment-chip--error {
+  border-color: var(--ag-ui-danger);
+  color: var(--ag-ui-danger);
+}
+
+.attachment-chip-name {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  max-width: 14ch;
+}
+
+.attachment-chip-size {
+  color: var(--ag-ui-muted);
+  white-space: nowrap;
+}
+
+.attachment-chip--error .attachment-chip-size {
+  color: var(--ag-ui-danger);
+}
+
+/* The progress bar fills as the file uploads. */
+.attachment-chip-bar {
+  flex-basis: 100%;
+  height: 3px;
+  border-radius: 2px;
+  background: var(--ag-ui-border);
+  overflow: hidden;
+}
+
+.attachment-chip-bar-fill {
+  height: 100%;
+  background: var(--ag-ui-accent);
+  transition: width 0.15s ease;
+}
+
+.attachment-chip-remove,
+.attachment-chip-retry {
+  border: none;
+  background: none;
+  color: inherit;
+  cursor: pointer;
+  padding: 0;
+  line-height: 1;
+  opacity: 0.7;
+}
+
+.attachment-chip-remove:hover,
+.attachment-chip-retry:hover {
+  opacity: 1;
+}
+
+/* A subtle outline while a file is dragged over the shell. */
+.chat--dragover {
+  outline: 2px dashed var(--ag-ui-accent);
+  outline-offset: -4px;
+}
+
 /* Muted "⏹ Stopped" line after a cancelled run — a note, not an error bubble. */
 .stopped-note {
   align-self: flex-start;

package/src/version.ts

@@ -1 +1 @@
-export const VERSION: string = "0.5.0";
+export const VERSION: string = "0.6.0";