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

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.6.0";
+export const VERSION: string = "0.7.0";