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

package/src/ui/attachment_tray.ts

@@ -0,0 +1,243 @@
+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";
+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;
+}
+
+/**
+ * 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;
+  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: "",
+    };
+    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 this.#strings.tooLarge.replace("{size}", formatBytes(this.#config.maxBytes));
+    }
+    if (!accepts(this.#config.accept, file)) {
+      return this.#strings.fileTypeNotAllowed;
+    }
+    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 : this.#strings.uploadFailed;
+      })
+      .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 = 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.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 {
+  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/confirmation_card.ts

@@ -1,10 +1,12 @@
+import { DEFAULT_UI_STRINGS, type UiStrings } from "./ui_strings.js";
+
 /** What the inline confirmation card displays. */
 export interface ConfirmationRequest {
   toolName: string;
   args: Record<string, unknown>;
   /**
    * Human-readable prompt (from the tool's `x-confirm` metadata), e.g.
-   * "Activate this project?". Falls back to a generic `Run "<tool>"?`.
+   * "Activate this project?". Falls back to the generic `confirmRun` template.
    */
   message?: string;
 }
@@ -14,6 +16,7 @@ function actionButton(modifier: string, label: string): HTMLButtonElement {
   const button = document.createElement("button");
   button.type = "button";
   button.className = `confirm-btn confirm-btn--${modifier}`;
+  button.setAttribute("part", `confirm-button confirm-${modifier}`);
   button.textContent = label;
   return button;
 }
@@ -26,6 +29,8 @@ export interface ConfirmationOptions {
    * pending confirmation when the user cancels the whole run.
    */
   signal?: AbortSignal;
+  /** Localized strings; defaults to the English {@link DEFAULT_UI_STRINGS}. */
+  strings?: UiStrings;
 }
 
 /**
@@ -43,26 +48,31 @@ export function requestConfirmation(
   request: ConfirmationRequest,
   options: ConfirmationOptions = {},
 ): Promise<boolean> {
+  const strings = options.strings ?? DEFAULT_UI_STRINGS;
   return new Promise<boolean>((resolve) => {
     const card = document.createElement("div");
     card.className = "confirm";
+    card.setAttribute("part", "confirm");
     card.setAttribute("data-tool-name", request.toolName);
     card.setAttribute("role", "group");
-    card.setAttribute("aria-label", "Confirm action");
+    card.setAttribute("aria-label", strings.confirmAction);
 
     const body = document.createElement("div");
     body.className = "confirm-body";
-    body.textContent = request.message ?? `Run “${request.toolName}”?`;
+    body.setAttribute("part", "confirm-body");
+    body.textContent = request.message ?? strings.confirmRun.replace("{tool}", request.toolName);
 
     const args = document.createElement("pre");
     args.className = "confirm-args";
+    args.setAttribute("part", "confirm-args");
     args.textContent = JSON.stringify(request.args, null, 2);
 
     const actions = document.createElement("div");
     actions.className = "confirm-actions";
+    actions.setAttribute("part", "confirm-actions");
 
-    const cancel = actionButton("cancel", "Cancel");
-    const confirm = actionButton("confirm", "Confirm");
+    const cancel = actionButton("cancel", strings.cancel);
+    const confirm = actionButton("confirm", strings.confirm);
 
     let settled = false;
     const close = (accepted: boolean): void => {

package/src/ui/relative_time.ts

@@ -1,28 +1,35 @@
+import { DEFAULT_UI_STRINGS, type UiStrings } from "./ui_strings.js";
+
 /**
  * A compact relative timestamp for a thread row — e.g. `"just now"`, `"5m ago"`,
  * `"3h ago"`, `"2d ago"`, `"4w ago"`.
  *
  * `now` is injectable so callers (and tests) can pin the reference point; it
  * defaults to the current time. A timestamp in the future (clock skew) reads as
- * `"just now"`. Kept locale-independent on purpose so the rendered label is
- * stable across environments.
+ * `"just now"`. The unit words come from {@link UiStrings} (the `{n}` token is
+ * filled in here) so a localized host translates them; the bucketing stays
+ * integer-rounded and locale-neutral.
  */
-export function relativeTime(timestamp: number, now: number = Date.now()): string {
+export function relativeTime(
+  timestamp: number,
+  now: number = Date.now(),
+  strings: UiStrings = DEFAULT_UI_STRINGS,
+): string {
   const seconds = Math.round((now - timestamp) / 1000);
   if (seconds < 60) {
-    return "just now";
+    return strings.justNow;
   }
   const minutes = Math.round(seconds / 60);
   if (minutes < 60) {
-    return `${minutes}m ago`;
+    return strings.minutesAgo.replace("{n}", String(minutes));
   }
   const hours = Math.round(minutes / 60);
   if (hours < 24) {
-    return `${hours}h ago`;
+    return strings.hoursAgo.replace("{n}", String(hours));
   }
   const days = Math.round(hours / 24);
   if (days < 7) {
-    return `${days}d ago`;
+    return strings.daysAgo.replace("{n}", String(days));
   }
-  return `${Math.round(days / 7)}w ago`;
+  return strings.weeksAgo.replace("{n}", String(Math.round(days / 7)));
 }

package/src/ui/styles.ts

@@ -133,6 +133,71 @@ export const STYLES = `
   --ag-ui-radius: 0;
 }
 
+/* Sidebar (CUST-3): a full-height docked panel that slides open/closed and
+   collapses to a slim icon rail (not the floating launcher). Docked right by
+   default; data-side="left" docks it left. Overlay by default — set
+   --ag-ui-position: static (and place this element in your own layout) for a
+   host-managed push instead. */
+:host([placement="sidebar"]) {
+  --ag-ui-inset: 0 0 0 auto;
+  --ag-ui-width: 420px;
+  --ag-ui-height: 100vh;
+  --ag-ui-max-height: 100vh;
+  --ag-ui-radius: 0;
+  --ag-ui-rail-width: 52px;
+  transition: width 0.28s ease;
+}
+
+:host([placement="sidebar"][data-side="left"]) {
+  --ag-ui-inset: 0 auto 0 0;
+}
+
+:host([placement="sidebar"]) .chat {
+  transition: transform 0.28s ease;
+}
+
+/* Collapsed sidebar: shrink the host to the rail width, hide the panel, and
+   reveal the rail. Higher specificity than the generic collapse rules, so it
+   wins regardless of source order. */
+:host([placement="sidebar"][collapsed]) {
+  width: var(--ag-ui-rail-width);
+  height: 100vh;
+  max-height: 100vh;
+  bottom: 0;
+}
+
+:host([placement="sidebar"][collapsed]) .chat {
+  display: none;
+}
+
+/* The rail is a sibling of the panel (so it survives the panel being hidden);
+   shown only for a collapsed sidebar. */
+.rail {
+  display: none;
+  border: none;
+  font: inherit;
+}
+
+:host([placement="sidebar"][collapsed]) .rail {
+  display: flex;
+  position: absolute;
+  inset: 0;
+  align-items: flex-start;
+  justify-content: center;
+  padding-top: 16px;
+  border: 1px solid var(--ag-ui-border);
+  background: var(--ag-ui-header-bg);
+  color: var(--ag-ui-header-fg);
+  cursor: pointer;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :host([placement="sidebar"]),
+  :host([placement="sidebar"]) .chat {
+    transition: none;
+  }
+}
+
 /* Embedded: drop the floating chrome and the high z-index stacking context so
    the widget lives in the host's own layout (fixes overlay/z-index clashes). */
 :host([placement="embedded"]) {
@@ -170,12 +235,33 @@ export const STYLES = `
 }
 
 .header-title {
+  flex: 1;
+  min-width: 0;
   font-weight: 600;
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
 }
 
+/* Header / launcher icon holder (CUST-2): a slot, with a data-icon-url <img>
+   fallback, sized via --ag-ui-icon-size. */
+.icon-holder {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: none;
+  width: var(--ag-ui-icon-size, 22px);
+  height: var(--ag-ui-icon-size, 22px);
+  line-height: 1;
+}
+
+.icon-img {
+  width: 100%;
+  height: 100%;
+  object-fit: contain;
+  border-radius: var(--ag-ui-icon-radius, 4px);
+}
+
 .header-controls {
   display: flex;
   gap: 2px;
@@ -231,6 +317,18 @@ export const STYLES = `
   gap: var(--ag-ui-space);
 }
 
+/* Empty-state region (CUST-1 slot): centred while it's the only thing in the
+   list, hidden as soon as a message, card, or pending indicator renders. */
+.empty {
+  margin: auto;
+  text-align: center;
+  color: var(--ag-ui-muted);
+}
+
+.empty[hidden] {
+  display: none;
+}
+
 .message {
   max-width: 80%;
   padding: var(--ag-ui-msg-pad);
@@ -506,6 +604,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;