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

package/src/ui/thread_drawer.ts

@@ -1,5 +1,6 @@
 import type { ThreadMeta } from "../core/conversation_store.js";
 import { relativeTime } from "./relative_time.js";
+import { DEFAULT_UI_STRINGS, type UiStrings } from "./ui_strings.js";
 
 /** Actions the host ({@link AgUiChat}) wires to the drawer's rows. */
 export interface ThreadDrawerCallbacks {
@@ -20,52 +21,76 @@ export interface ThreadDrawerCallbacks {
  * {@link element}, toggles it, feeds rows via {@link setThreads}, and acts on
  * the callbacks. The drawer is a *view*: it does not mutate the store; after a
  * callback the host updates the store and calls {@link setThreads} to refresh.
+ *
+ * All visible text comes from {@link UiStrings}; {@link setStrings} re-localizes
+ * a drawer the host built before its strings resolved.
  */
 export class ThreadDrawer {
   /** The drawer root (backdrop + panel). Append to the chat shell; hidden until opened. */
   readonly element: HTMLDivElement;
 
   readonly #callbacks: ThreadDrawerCallbacks;
+  readonly #panel: HTMLDivElement;
+  readonly #heading: HTMLSpanElement;
+  readonly #newButton: HTMLButtonElement;
   readonly #list: HTMLDivElement;
+  #strings: UiStrings;
   #threads: readonly ThreadMeta[] = [];
   #activeId = "";
 
-  constructor(callbacks: ThreadDrawerCallbacks) {
+  constructor(callbacks: ThreadDrawerCallbacks, strings: UiStrings = DEFAULT_UI_STRINGS) {
     this.#callbacks = callbacks;
+    this.#strings = strings;
 
     this.element = document.createElement("div");
     this.element.className = "drawer";
+    this.element.setAttribute("part", "drawer");
     this.element.hidden = true;
 
     const backdrop = document.createElement("div");
     backdrop.className = "drawer-backdrop";
+    backdrop.setAttribute("part", "drawer-backdrop");
     backdrop.addEventListener("click", () => this.close());
 
-    const panel = document.createElement("div");
-    panel.className = "drawer-panel";
-    panel.setAttribute("role", "dialog");
-    panel.setAttribute("aria-label", "Chat history");
+    this.#panel = document.createElement("div");
+    this.#panel.className = "drawer-panel";
+    this.#panel.setAttribute("part", "drawer-panel");
+    this.#panel.setAttribute("role", "dialog");
+    this.#panel.setAttribute("aria-label", strings.chatHistory);
 
     const header = document.createElement("div");
     header.className = "drawer-header";
-    const heading = document.createElement("span");
-    heading.className = "drawer-title";
-    heading.textContent = "Chats";
-    const newButton = document.createElement("button");
-    newButton.type = "button";
-    newButton.className = "drawer-new";
-    newButton.textContent = "New chat";
-    newButton.addEventListener("click", () => {
+    header.setAttribute("part", "drawer-header");
+    this.#heading = document.createElement("span");
+    this.#heading.className = "drawer-title";
+    this.#heading.setAttribute("part", "drawer-title");
+    this.#heading.textContent = strings.chats;
+    this.#newButton = document.createElement("button");
+    this.#newButton.type = "button";
+    this.#newButton.className = "drawer-new";
+    this.#newButton.setAttribute("part", "drawer-new");
+    this.#newButton.textContent = strings.newChat;
+    this.#newButton.addEventListener("click", () => {
       this.close();
       this.#callbacks.onNew();
     });
-    header.append(heading, newButton);
+    header.append(this.#heading, this.#newButton);
 
     this.#list = document.createElement("div");
     this.#list.className = "drawer-list";
+    this.#list.setAttribute("part", "drawer-list");
 
-    panel.append(header, this.#list);
-    this.element.append(backdrop, panel);
+    this.#panel.append(header, this.#list);
+    this.element.append(backdrop, this.#panel);
+  }
+
+  /** Re-localize the drawer's chrome and rows (the host calls this on connect). */
+  setStrings(strings: UiStrings): void {
+    this.#strings = strings;
+    this.#panel.setAttribute("aria-label", strings.chatHistory);
+    this.#heading.textContent = strings.chats;
+    this.#newButton.textContent = strings.newChat;
+    this.#renderList();
   }
 
   isOpen(): boolean {
@@ -96,7 +121,8 @@ export class ThreadDrawer {
     if (this.#threads.length === 0) {
       const empty = document.createElement("div");
       empty.className = "drawer-empty";
-      empty.textContent = "No conversations yet.";
+      empty.setAttribute("part", "drawer-empty");
+      empty.textContent = this.#strings.noConversations;
       this.#list.appendChild(empty);
       return;
     }
@@ -108,6 +134,7 @@ export class ThreadDrawer {
   #renderRow(meta: ThreadMeta): HTMLDivElement {
     const row = document.createElement("div");
     row.className = "drawer-row";
+    row.setAttribute("part", "drawer-row");
     if (meta.threadId === this.#activeId) {
       row.classList.add("drawer-row--active");
     }
@@ -115,12 +142,13 @@ export class ThreadDrawer {
     const select = document.createElement("button");
     select.type = "button";
     select.className = "drawer-row-select";
+    select.setAttribute("part", "drawer-row-select");
     const title = document.createElement("span");
     title.className = "drawer-row-title";
     title.textContent = meta.title;
     const time = document.createElement("span");
     time.className = "drawer-row-time";
-    time.textContent = relativeTime(meta.updatedAt);
+    time.textContent = relativeTime(meta.updatedAt, undefined, this.#strings);
     const preview = document.createElement("span");
     preview.className = "drawer-row-preview";
     preview.textContent = meta.preview;
@@ -133,16 +161,16 @@ export class ThreadDrawer {
     const rename = document.createElement("button");
     rename.type = "button";
     rename.className = "drawer-row-rename";
-    rename.title = "Rename";
-    rename.setAttribute("aria-label", "Rename conversation");
+    rename.title = this.#strings.rename;
+    rename.setAttribute("aria-label", this.#strings.renameConversation);
     rename.textContent = "✎";
     rename.addEventListener("click", () => this.#startRename(row, meta));
 
     const remove = document.createElement("button");
     remove.type = "button";
     remove.className = "drawer-row-delete";
-    remove.title = "Delete";
-    remove.setAttribute("aria-label", "Delete conversation");
+    remove.title = this.#strings.delete;
+    remove.setAttribute("aria-label", this.#strings.deleteConversation);
     remove.textContent = "🗑";
     remove.addEventListener("click", () => this.#confirmDelete(row, meta));
 
@@ -183,16 +211,16 @@ export class ThreadDrawer {
     confirm.className = "drawer-confirm";
     const label = document.createElement("span");
     label.className = "drawer-confirm-label";
-    label.textContent = "Delete?";
+    label.textContent = this.#strings.deletePrompt;
     const yes = document.createElement("button");
     yes.type = "button";
     yes.className = "drawer-confirm-yes";
-    yes.textContent = "Delete";
+    yes.textContent = this.#strings.delete;
     yes.addEventListener("click", () => this.#callbacks.onDelete(meta.threadId));
     const no = document.createElement("button");
     no.type = "button";
     no.className = "drawer-confirm-no";
-    no.textContent = "Cancel";
+    no.textContent = this.#strings.cancel;
     no.addEventListener("click", () => this.#renderList());
     confirm.append(label, yes, no);
     row.replaceChildren(confirm);

package/src/ui/tool_call_card.ts

@@ -1,4 +1,5 @@
 import { TOOL_CALL_STATUS, TOOL_DISPLAY } from "../constants.js";
+import { DEFAULT_UI_STRINGS, type UiStrings } from "./ui_strings.js";
 
 /** Any state a tool-call card can be in. */
 export type ToolCallStatus = (typeof TOOL_CALL_STATUS)[keyof typeof TOOL_CALL_STATUS];
@@ -9,20 +10,24 @@ export type ToolDisplayMode = (typeof TOOL_DISPLAY)[keyof typeof TOOL_DISPLAY];
 /** The terminal states a card settles into (everything but `pending`). */
 export type SettledStatus = Exclude<ToolCallStatus, typeof TOOL_CALL_STATUS.PENDING>;
 
-/** Short pill text shown for each status. */
-const STATUS_LABEL: Record<ToolCallStatus, string> = {
-  [TOOL_CALL_STATUS.PENDING]: "running…",
-  [TOOL_CALL_STATUS.DONE]: "✓ done",
-  [TOOL_CALL_STATUS.ERROR]: "⚠ error",
-  [TOOL_CALL_STATUS.DECLINED]: "⊘ declined",
-};
+/** Short pill text shown for each status, drawn from the string table. */
+function statusLabels(strings: UiStrings): Record<ToolCallStatus, string> {
+  return {
+    [TOOL_CALL_STATUS.PENDING]: strings.toolRunning,
+    [TOOL_CALL_STATUS.DONE]: strings.toolDone,
+    [TOOL_CALL_STATUS.ERROR]: strings.toolError,
+    [TOOL_CALL_STATUS.DECLINED]: strings.toolDeclined,
+  };
+}
 
 /** Toggle-button label for each settled outcome's collapsible body (full mode). */
-const RESULT_LABEL: Record<SettledStatus, string> = {
-  [TOOL_CALL_STATUS.DONE]: "Result",
-  [TOOL_CALL_STATUS.ERROR]: "Error",
-  [TOOL_CALL_STATUS.DECLINED]: "Declined",
-};
+function resultLabels(strings: UiStrings): Record<SettledStatus, string> {
+  return {
+    [TOOL_CALL_STATUS.DONE]: strings.resultLabel,
+    [TOOL_CALL_STATUS.ERROR]: strings.errorLabel,
+    [TOOL_CALL_STATUS.DECLINED]: strings.declinedLabel,
+  };
+}
 
 /**
  * A live tool-call card for the chat transcript.
@@ -37,7 +42,8 @@ const RESULT_LABEL: Record<SettledStatus, string> = {
  * - `full` — the result (or error / decline message) behind its own toggle.
  *
  * Pure DOM (no framework); the host appends {@link element} into its shadow
- * root and themes it via the `--ag-ui-*` custom properties.
+ * root and themes it via the `--ag-ui-*` custom properties or the exposed
+ * `tool-card*` `part`s. All visible text is sourced from {@link UiStrings}.
  */
 export class ToolCallCard {
   /** The card's root element; append this into the message list. */
@@ -46,33 +52,41 @@ export class ToolCallCard {
   readonly #status: HTMLSpanElement;
   readonly #mode: ToolDisplayMode;
   readonly #args: Record<string, unknown>;
+  readonly #strings: UiStrings;
+  #settled = false;
 
   constructor(
     name: string,
     args: Record<string, unknown>,
     mode: ToolDisplayMode = TOOL_DISPLAY.FULL,
     summary?: string,
+    strings: UiStrings = DEFAULT_UI_STRINGS,
   ) {
     this.#mode = mode;
     this.#args = args;
+    this.#strings = strings;
 
     this.element = document.createElement("div");
     this.element.className = "tool-call";
+    this.element.setAttribute("part", "tool-card");
     this.element.setAttribute("data-tool-name", name);
     this.element.setAttribute("data-status", TOOL_CALL_STATUS.PENDING);
     this.element.setAttribute("data-display", mode);
 
     const head = document.createElement("div");
     head.className = "tool-call-head";
+    head.setAttribute("part", "tool-card-head");
 
     const label = document.createElement("span");
     label.className = "tool-call-name";
+    label.setAttribute("part", "tool-card-name");
     // A server-provided `x-summary` label reads better than the raw tool name.
     label.textContent = `🔧 ${summary ?? name}`;
 
     this.#status = document.createElement("span");
     this.#status.className = "tool-call-status";
-    this.#status.textContent = STATUS_LABEL[TOOL_CALL_STATUS.PENDING];
+    this.#status.setAttribute("part", "tool-card-status");
+    this.#status.textContent = statusLabels(strings)[TOOL_CALL_STATUS.PENDING];
 
     head.append(label, this.#status);
     this.element.append(head);
@@ -80,19 +94,26 @@ export class ToolCallCard {
     if (mode === TOOL_DISPLAY.FULL) {
       const argsEl = document.createElement("pre");
       argsEl.className = "tool-call-args";
+      argsEl.setAttribute("part", "tool-card-args");
       argsEl.textContent = JSON.stringify(args, null, 2);
       this.element.append(argsEl);
     }
   }
 
+  /** Whether {@link settle} has already run (so a terminal sweep can skip it). */
+  get settled(): boolean {
+    return this.#settled;
+  }
+
   /**
    * Flip the status pill to ``status`` and, unless in `minimal` mode, append a
    * collapsed body behind a click-to-expand toggle: the result alone (`full`),
    * or the args + result together (`compact`).
    */
   settle(status: SettledStatus, text: string): void {
+    this.#settled = true;
     this.element.setAttribute("data-status", status);
-    this.#status.textContent = STATUS_LABEL[status];
+    this.#status.textContent = statusLabels(this.#strings)[status];
 
     if (this.#mode === TOOL_DISPLAY.MINIMAL) {
       return;
@@ -101,17 +122,19 @@ export class ToolCallCard {
     const toggle = document.createElement("button");
     toggle.type = "button";
     toggle.className = "tool-call-toggle";
+    toggle.setAttribute("part", "tool-card-toggle");
     toggle.setAttribute("aria-expanded", "false");
 
     const output = document.createElement("pre");
     output.className = "tool-call-result";
+    output.setAttribute("part", "tool-card-result");
     output.hidden = true;
 
     if (this.#mode === TOOL_DISPLAY.COMPACT) {
-      toggle.textContent = "Details";
+      toggle.textContent = this.#strings.details;
       output.textContent = `args: ${JSON.stringify(this.#args)}\n\n${text}`;
     } else {
-      toggle.textContent = RESULT_LABEL[status];
+      toggle.textContent = resultLabels(this.#strings)[status];
       output.textContent = text;
     }
 

package/src/ui/ui_strings.ts

@@ -0,0 +1,208 @@
+/**
+ * The flat table of every user-facing string the chat shell renders — labels,
+ * placeholders, `aria-label`s, and `title` tooltips. A localizable seam, not a
+ * framework: a host overrides any subset (via the element's `strings` property
+ * or its `data-strings` JSON attribute) and the rest fall back to the English
+ * defaults.
+ *
+ * A handful of values are **templates** carrying `{token}` placeholders the call
+ * site fills in (e.g. `minutesAgo` → `"{n}m ago"`); the token names are noted on
+ * each key. Translators keep the token verbatim.
+ *
+ * This module is one cohesive unit — the `UiStrings` shape, its `DEFAULT_UI_STRINGS`
+ * constant-like backing, and the {@link mergeUiStrings} merge over those defaults —
+ * so it bends the one-symbol-per-file rule the way `tool_call_card.ts` (class +
+ * its types) and `route_map.ts` (factory + its types) already do.
+ */
+export interface UiStrings {
+  // ── Header ────────────────────────────────────────────────────────────────
+  /** Default header title (the `title-text` attribute overrides per element). */
+  title: string;
+  /** History button + drawer dialog label. */
+  chatHistory: string;
+  /** New-chat button (header + drawer). */
+  newChat: string;
+  /** Collapse button. */
+  collapse: string;
+  /** Expand affordance (the sidebar rail toggle). */
+  expand: string;
+
+  // ── Messages region ─────────────────────────────────────────────────────────
+  /** `aria-label` of the scrolling message log. */
+  conversation: string;
+  /** `aria-label` of the "thinking" pending indicator. */
+  thinking: string;
+  /** The muted note after a cancelled run. */
+  stopped: string;
+  /** Error shown when the stream drops without a terminal AG-UI event. */
+  connectionLost: string;
+  /** Fallback when a tool call produced no result. */
+  noResult: string;
+  /** Tool-result content when the user declines a confirmed action. */
+  declinedAction: string;
+  /** A navigating tool's card text while the page reloads. */
+  navigating: string;
+  /** Missing-placeholder skill hint. Tokens: `{title}`, `{fields}`. */
+  skillNeeds: string;
+
+  // ── Composer ────────────────────────────────────────────────────────────────
+  /** `aria-label` of the message textarea. */
+  message: string;
+  /** Placeholder of the message textarea. */
+  inputPlaceholder: string;
+  /** Send button (idle composer). */
+  send: string;
+  /** Stop button (composer while a run is in flight). */
+  stop: string;
+  /** Attach-files button. */
+  attachFiles: string;
+
+  // ── Tool-call card ──────────────────────────────────────────────────────────
+  /** Status pill while the call runs. */
+  toolRunning: string;
+  /** Status pill on success. */
+  toolDone: string;
+  /** Status pill on error. */
+  toolError: string;
+  /** Status pill on a declined call. */
+  toolDeclined: string;
+  /** Toggle label revealing a successful result (full mode). */
+  resultLabel: string;
+  /** Toggle label revealing an error (full mode). */
+  errorLabel: string;
+  /** Toggle label revealing a declined call (full mode). */
+  declinedLabel: string;
+  /** Toggle label revealing args + result together (compact mode). */
+  details: string;
+
+  // ── Confirmation card ───────────────────────────────────────────────────────
+  /** `aria-label` of the inline confirmation card. */
+  confirmAction: string;
+  /** Generic confirmation prompt when a tool has no `x-confirm`. Token: `{tool}`. */
+  confirmRun: string;
+  /** Confirm button. */
+  confirm: string;
+  /** Cancel button (confirmation + delete confirm). */
+  cancel: string;
+
+  // ── Chat-history drawer ─────────────────────────────────────────────────────
+  /** Drawer heading. */
+  chats: string;
+  /** Empty-state line when there are no threads. */
+  noConversations: string;
+  /** Rename row button (`title`). */
+  rename: string;
+  /** Rename row button `aria-label`. */
+  renameConversation: string;
+  /** Delete row button (`title`) + the inline-confirm action. */
+  delete: string;
+  /** Delete row button `aria-label`. */
+  deleteConversation: string;
+  /** Inline delete-confirm prompt. */
+  deletePrompt: string;
+
+  // ── Attachments ─────────────────────────────────────────────────────────────
+  /** Oversize rejection. Token: `{size}`. */
+  tooLarge: string;
+  /** Disallowed-type rejection. */
+  fileTypeNotAllowed: string;
+  /** Generic upload failure (when the error carries no message). */
+  uploadFailed: string;
+  /** Retry-upload button (`title`). */
+  retry: string;
+  /** Retry-upload button `aria-label`. */
+  retryUpload: string;
+  /** Remove-attachment button (`title`). */
+  remove: string;
+  /** Remove-attachment button `aria-label`. */
+  removeAttachment: string;
+
+  // ── Relative time (drawer rows) ─────────────────────────────────────────────
+  /** Under a minute ago. */
+  justNow: string;
+  /** Minutes ago. Token: `{n}`. */
+  minutesAgo: string;
+  /** Hours ago. Token: `{n}`. */
+  hoursAgo: string;
+  /** Days ago. Token: `{n}`. */
+  daysAgo: string;
+  /** Weeks ago. Token: `{n}`. */
+  weeksAgo: string;
+}
+
+/** The built-in English strings — the fallback every override merges over. */
+export const DEFAULT_UI_STRINGS: UiStrings = {
+  title: "Assistant",
+  chatHistory: "Chat history",
+  newChat: "New chat",
+  collapse: "Collapse",
+  expand: "Expand",
+
+  conversation: "Conversation",
+  thinking: "Assistant is thinking…",
+  stopped: "⏹ Stopped",
+  connectionLost: "Connection lost",
+  noResult: "No result returned.",
+  declinedAction: "User declined the action.",
+  navigating: "Navigating…",
+  skillNeeds: "“{title}” needs: {fields}",
+
+  message: "Message",
+  inputPlaceholder: "Ask anything…",
+  send: "Send",
+  stop: "Stop",
+  attachFiles: "Attach files",
+
+  toolRunning: "running…",
+  toolDone: "✓ done",
+  toolError: "⚠ error",
+  toolDeclined: "⊘ declined",
+  resultLabel: "Result",
+  errorLabel: "Error",
+  declinedLabel: "Declined",
+  details: "Details",
+
+  confirmAction: "Confirm action",
+  confirmRun: "Run “{tool}”?",
+  confirm: "Confirm",
+  cancel: "Cancel",
+
+  chats: "Chats",
+  noConversations: "No conversations yet.",
+  rename: "Rename",
+  renameConversation: "Rename conversation",
+  delete: "Delete",
+  deleteConversation: "Delete conversation",
+  deletePrompt: "Delete?",
+
+  tooLarge: "Too large (max {size})",
+  fileTypeNotAllowed: "File type not allowed",
+  uploadFailed: "upload failed",
+  retry: "Retry",
+  retryUpload: "Retry upload",
+  remove: "Remove",
+  removeAttachment: "Remove attachment",
+
+  justNow: "just now",
+  minutesAgo: "{n}m ago",
+  hoursAgo: "{n}h ago",
+  daysAgo: "{n}d ago",
+  weeksAgo: "{n}w ago",
+};
+
+/**
+ * Merge a partial set of overrides over {@link DEFAULT_UI_STRINGS}, yielding a
+ * complete {@link UiStrings}. Keys whose override is `undefined` keep the
+ * default (so a `data-strings` JSON with only a few keys — or a property carrying
+ * explicit `undefined` — leaves the rest English).
+ */
+export function mergeUiStrings(overrides: Partial<UiStrings>): UiStrings {
+  const merged: UiStrings = { ...DEFAULT_UI_STRINGS };
+  for (const key of Object.keys(overrides) as (keyof UiStrings)[]) {
+    const value = overrides[key];
+    if (value !== undefined) {
+      merged[key] = value;
+    }
+  }
+  return merged;
+}

package/src/version.ts

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