@artooi/ag-ui-web-component 0.38.0 → 0.40.0

package/src/ui/history/relative_time.ts

@@ -1,3 +1,4 @@
+import { fillUiString } from "../fill_ui_string.js";
 import { DEFAULT_UI_STRINGS, type UiStrings } from "../ui_strings.js";
 
 /**
@@ -24,17 +25,17 @@ export function relativeTime(
   }
   const minutes = Math.round(seconds / 60);
   if (minutes < 60) {
-    return strings.minutesAgo.replace("{n}", String(minutes));
+    return fillUiString(strings.minutesAgo, { n: minutes });
   }
   const hours = Math.round(minutes / 60);
   if (hours < 24) {
-    return strings.hoursAgo.replace("{n}", String(hours));
+    return fillUiString(strings.hoursAgo, { n: hours });
   }
   const days = Math.round(hours / 24);
   if (days < 7) {
-    return strings.daysAgo.replace("{n}", String(days));
+    return fillUiString(strings.daysAgo, { n: days });
   }
-  return strings.weeksAgo.replace("{n}", String(Math.round(days / 7)));
+  return fillUiString(strings.weeksAgo, { n: Math.round(days / 7) });
 }
 
 /**

package/src/ui/history/thread_drawer.ts

@@ -20,15 +20,6 @@ export interface ThreadDrawerCallbacks {
   readonly onRename: (threadId: string, title: string) => void;
   /** A row was deleted (after the inline confirm). */
   readonly onDelete: (threadId: string) => void;
-  /**
-   * The list opened or closed.
-   *
-   * There are five ways out of it -- the close control, the backdrop, Escape,
-   * picking a row and starting a new chat -- and only two of them go through
-   * the host. A docked list moves the transcript over, so the host has to know
-   * about all five or the transcript stays shifted around nothing.
-   */
-  readonly onVisibility?: (open: boolean) => void;
 }
 
 /**
@@ -62,17 +53,6 @@ export class ThreadDrawer {
   #filter: HTMLInputElement;
   /** The current filter text, lowercased once rather than per row. */
   #query = "";
-  /**
-   * Whether the list covers the conversation, or sits beside it.
-   *
-   * Everything a dialog implies follows from this and nothing else does: the
-   * modal role, the focus trap, and taking focus on open. A list docked beside
-   * a full-page conversation is a region of that page -- telling assistive
-   * technology to ignore the rest of the document while it is showing would be
-   * a lie, and stealing focus into it would interrupt someone mid-sentence to
-   * announce a list they can already see.
-   */
-  #modal = true;
 
   /** The element focused before the drawer opened, restored on close. */
   #lastFocused: HTMLElement | null = null;
@@ -186,21 +166,6 @@ export class ThreadDrawer {
     this.#renderList();
   }
 
-  /**
-   * Whether the list is a dialog over the conversation or a rail beside it.
-   * The host decides, because only the placement knows whether there is room.
-   */
-  setModal(modal: boolean): void {
-    this.#modal = modal;
-    if (modal) {
-      this.#panel.setAttribute("role", "dialog");
-      this.#panel.setAttribute("aria-modal", "true");
-    } else {
-      this.#panel.setAttribute("role", "region");
-      this.#panel.removeAttribute("aria-modal");
-    }
-  }
-
   isOpen(): boolean {
     return !this.element.hidden;
   }
@@ -213,10 +178,7 @@ export class ThreadDrawer {
     // the panel (its first control) so keyboard users land inside the dialog.
     this.#lastFocused = this.#activeElement() as HTMLElement | null;
     this.element.hidden = false;
-    if (this.#modal) {
-      this.#newButton.focus();
-    }
-    this.#callbacks.onVisibility?.(true);
+    this.#newButton.focus();
   }
 
   close(): void {
@@ -224,13 +186,8 @@ export class ThreadDrawer {
       return;
     }
     this.element.hidden = true;
-    // Only if it was taken. Restoring focus that was never moved would pull it
-    // back from wherever the user has since put it.
-    if (this.#modal) {
-      this.#lastFocused?.focus();
-    }
+    this.#lastFocused?.focus();
     this.#lastFocused = null;
-    this.#callbacks.onVisibility?.(false);
   }
 
   toggle(): void {
@@ -253,11 +210,7 @@ export class ThreadDrawer {
       this.close();
       return;
     }
-    // Escape still closes a docked rail -- it is a way out, not a modal
-    // convention -- but nothing beyond this point applies to one. Tabbing out
-    // of a list that sits beside the conversation should reach the
-    // conversation, which is the whole difference.
-    if (event.key !== "Tab" || !this.#modal) {
+    if (event.key !== "Tab") {
       return;
     }
     const focusables = Array.from(

package/src/ui/interrupts/confirmation_card.ts

@@ -1,3 +1,4 @@
+import { fillUiString } from "../fill_ui_string.js";
 import { DEFAULT_UI_STRINGS, type UiStrings } from "../ui_strings.js";
 
 /** What the inline confirmation card displays. */
@@ -77,7 +78,8 @@ export function requestConfirmation(
     const body = document.createElement("div");
     body.className = "confirm-body";
     body.setAttribute("part", "confirm-body");
-    body.textContent = request.message ?? strings.confirmRun.replace("{tool}", request.toolName);
+    body.textContent =
+      request.message ?? fillUiString(strings.confirmRun, { tool: request.toolName });
 
     const args = document.createElement("pre");
     args.className = "confirm-args";
@@ -94,7 +96,7 @@ export function requestConfirmation(
     const always =
       options.onAlwaysAllow === undefined
         ? null
-        : actionButton("always", strings.confirmAlways.replace("{tool}", request.toolName));
+        : actionButton("always", fillUiString(strings.confirmAlways, { tool: request.toolName }));
     const confirm = actionButton("confirm", strings.confirm);
 
     let settled = false;

package/src/ui/interrupts/pending_decision.ts

@@ -0,0 +1,34 @@
+/**
+ * The decision a run is suspended on, and the one way to abandon it.
+ *
+ * A run pauses on a person in three places -- a client-side confirmation, a
+ * batch of server interrupts, and the `ask_user` question -- and a Stop has to
+ * reach whichever of them is open. Each used to assign the element's own abort
+ * controller directly, so four places wrote one field and nothing said which
+ * of them owned it. Holding it here gives it one owner: a wait opens, the Stop
+ * aborts what is open, and the wait closes when it is answered.
+ *
+ * Owned one-to-one by an `<ag-ui-chat>`, and holding no state outside the
+ * instance.
+ */
+export class PendingDecision {
+  // Aborting this dismisses (declines) an open confirmation card when the run
+  // is cancelled while the card awaits a decision. One controller per wait.
+  #controller: AbortController | null = null;
+
+  /** Start waiting on a person; aborting the returned signal abandons the wait. */
+  open(): AbortSignal {
+    this.#controller = new AbortController();
+    return this.#controller.signal;
+  }
+
+  /** The wait was answered; a later Stop has nothing of this wait's to abandon. */
+  close(): void {
+    this.#controller = null;
+  }
+
+  /** Abandon whatever wait is open, resolving it as declined. A no-op when none is. */
+  abort(): void {
+    this.#controller?.abort();
+  }
+}

package/src/ui/placement/is_collapsible_placement.ts

@@ -0,0 +1,19 @@
+/**
+ * Whether `placement` has a collapsed state at all.
+ *
+ * `page` does not. It is a dedicated route rather than a panel sitting on
+ * someone else's page, so there is no "away" for it to go to: collapsing it
+ * left a strip of application chrome fixed over a route that no longer had an
+ * owner. It is also the placement that hides the launcher, so the usual way
+ * back does not exist here.
+ *
+ * The header hides its collapse control under this placement, but a control
+ * removed from the UI is not a state removed from the model -- the property,
+ * the attribute and a value restored from storage all still reach it. This is
+ * what the reachable paths are gated on; the stylesheet covers the one path
+ * that never passes through here, an attribute written straight onto the
+ * element.
+ */
+export function isCollapsiblePlacement(placement: string | null): boolean {
+  return placement !== "page";
+}

package/src/ui/placement/is_draggable_placement.ts

@@ -0,0 +1,23 @@
+/**
+ * Placements whose launcher can be dragged. The rest have nowhere to put it:
+ * a sidebar collapses to a full-height edge rail, "embedded" and "page" hide
+ * the launcher entirely and keep their header bar, and a full-bleed panel
+ * covers the screen it would be opening into.
+ */
+const DRAGGABLE_PLACEMENTS: ReadonlySet<string | null> = new Set([
+  null,
+  "",
+  "floating",
+  "bottom-left",
+]);
+
+/**
+ * Whether `placement` is one whose launcher can be dragged.
+ *
+ * Asked by two owners: the placement, deciding whether a gesture may move the
+ * widget, and the element, deciding whether a first mount starts collapsed --
+ * the corner placements are the two with a launcher to collapse to.
+ */
+export function isDraggablePlacement(placement: string | null): boolean {
+  return DRAGGABLE_PLACEMENTS.has(placement);
+}

package/src/ui/placement/launcher_drag.ts

@@ -21,6 +21,12 @@ export interface LauncherDragOptions {
    * per pointer move, and never per key repeat.
    */
   readonly commit: (left: number, top: number) => void;
+  /**
+   * Ends the launcher's own listeners when aborted. The launcher outlives the
+   * element's connection to the document and this is called on every connect,
+   * so without it a re-inserted element moved one arrow press two steps.
+   */
+  readonly signal: AbortSignal;
 }
 
 /**
@@ -55,6 +61,7 @@ const COARSE_STEP = 64;
  */
 export function enableLauncherDrag(launcher: HTMLElement, options: LauncherDragOptions): void {
   let suppressClick = false;
+  const { signal } = options;
 
   launcher.addEventListener(
     "click",
@@ -70,72 +77,76 @@ export function enableLauncherDrag(launcher: HTMLElement, options: LauncherDragO
       event.stopPropagation();
       event.preventDefault();
     },
-    true,
+    { capture: true, signal },
   );
 
-  launcher.addEventListener("pointerdown", (event: PointerEvent) => {
-    // Any suppression left armed by a drag that ended elsewhere dies here,
-    // before it can reach a click belonging to this new gesture.
-    suppressClick = false;
-    if (!options.enabled()) {
-      return;
-    }
-    const start = options.rect();
-    const originX = event.clientX;
-    const originY = event.clientY;
-    let dragging = false;
-
-    const onMove = (move: PointerEvent): void => {
-      const dx = move.clientX - originX;
-      const dy = move.clientY - originY;
-      if (!dragging && Math.hypot(dx, dy) < DRAG_THRESHOLD) {
+  launcher.addEventListener(
+    "pointerdown",
+    (event: PointerEvent) => {
+      // Any suppression left armed by a drag that ended elsewhere dies here,
+      // before it can reach a click belonging to this new gesture.
+      suppressClick = false;
+      if (!options.enabled()) {
         return;
       }
-      dragging = true;
-      launcher.setAttribute("data-dragging", "true");
-      // Measured from the box the press started on, never from the live one:
-      // reading it each move would chase the launcher as it moves and the
-      // travel would compound.
-      const next = clampLauncher(
-        { ...start, left: start.left + dx, top: start.top + dy },
-        options.viewport(),
-      );
-      options.apply(next.left, next.top);
-    };
+      const start = options.rect();
+      const originX = event.clientX;
+      const originY = event.clientY;
+      let dragging = false;
 
-    const onUp = (up: PointerEvent): void => {
-      window.removeEventListener("pointermove", onMove);
-      window.removeEventListener("pointerup", onUp);
-      window.removeEventListener("pointercancel", onUp);
-      if (!dragging) {
-        return;
-      }
-      launcher.removeAttribute("data-dragging");
-      suppressClick = true;
-      const next = clampLauncher(
-        {
-          ...start,
-          left: start.left + (up.clientX - originX),
-          top: start.top + (up.clientY - originY),
-        },
-        options.viewport(),
-      );
-      options.commit(next.left, next.top);
-    };
+      const onMove = (move: PointerEvent): void => {
+        const dx = move.clientX - originX;
+        const dy = move.clientY - originY;
+        if (!dragging && Math.hypot(dx, dy) < DRAG_THRESHOLD) {
+          return;
+        }
+        dragging = true;
+        launcher.setAttribute("data-dragging", "true");
+        // Measured from the box the press started on, never from the live one:
+        // reading it each move would chase the launcher as it moves and the
+        // travel would compound.
+        const next = clampLauncher(
+          { ...start, left: start.left + dx, top: start.top + dy },
+          options.viewport(),
+        );
+        options.apply(next.left, next.top);
+      };
 
-    // Listeners on `window`, not the launcher: a fast drag outruns the pointer
-    // and would otherwise strand it mid-move with no pointerup.
-    //
-    // pointercancel matters on touch, where it is routine rather than
-    // exceptional: the browser takes the pointer back for a scroll or a system
-    // gesture and never sends pointerup. Without this the move listeners stay
-    // attached and the drag stamp never clears, which leaves the launcher
-    // following a finger that has stopped and the element believing a gesture
-    // is still in flight.
-    window.addEventListener("pointermove", onMove);
-    window.addEventListener("pointerup", onUp);
-    window.addEventListener("pointercancel", onUp);
-  });
+      const onUp = (up: PointerEvent): void => {
+        window.removeEventListener("pointermove", onMove);
+        window.removeEventListener("pointerup", onUp);
+        window.removeEventListener("pointercancel", onUp);
+        if (!dragging) {
+          return;
+        }
+        launcher.removeAttribute("data-dragging");
+        suppressClick = true;
+        const next = clampLauncher(
+          {
+            ...start,
+            left: start.left + (up.clientX - originX),
+            top: start.top + (up.clientY - originY),
+          },
+          options.viewport(),
+        );
+        options.commit(next.left, next.top);
+      };
+
+      // Listeners on `window`, not the launcher: a fast drag outruns the pointer
+      // and would otherwise strand it mid-move with no pointerup.
+      //
+      // pointercancel matters on touch, where it is routine rather than
+      // exceptional: the browser takes the pointer back for a scroll or a system
+      // gesture and never sends pointerup. Without this the move listeners stay
+      // attached and the drag stamp never clears, which leaves the launcher
+      // following a finger that has stopped and the element believing a gesture
+      // is still in flight.
+      window.addEventListener("pointermove", onMove);
+      window.addEventListener("pointerup", onUp);
+      window.addEventListener("pointercancel", onUp);
+    },
+    { signal },
+  );
 
   // The position this key gesture has applied but not yet persisted. The
   // pointer path can commit inline because a drag has one unambiguous end; a
@@ -155,37 +166,41 @@ export function enableLauncherDrag(launcher: HTMLElement, options: LauncherDragO
   // Keyboard parity: a pointer-only move is unreachable without a mouse, and
   // the launcher has no equivalent control elsewhere. Arrow keys are free on a
   // button, so Enter and Space still expand.
-  launcher.addEventListener("keydown", (event: KeyboardEvent) => {
-    if (!options.enabled()) {
-      return;
-    }
-    const step = event.shiftKey ? COARSE_STEP : STEP;
-    const rect = options.rect();
-    let moved: { left: number; top: number } | null = null;
-    if (event.key === "ArrowLeft") {
-      moved = { left: rect.left - step, top: rect.top };
-    } else if (event.key === "ArrowRight") {
-      moved = { left: rect.left + step, top: rect.top };
-    } else if (event.key === "ArrowUp") {
-      moved = { left: rect.left, top: rect.top - step };
-    } else if (event.key === "ArrowDown") {
-      moved = { left: rect.left, top: rect.top + step };
-    }
-    if (moved === null) {
-      return;
-    }
-    event.preventDefault();
-    const next = clampLauncher({ ...rect, ...moved }, options.viewport());
-    // Live feedback per key event, persistence only when the gesture ends: a
-    // held arrow repeats at the OS rate, and committing here would put that
-    // many storage writes behind a single press.
-    options.apply(next.left, next.top);
-    pending = next;
-  });
+  launcher.addEventListener(
+    "keydown",
+    (event: KeyboardEvent) => {
+      if (!options.enabled()) {
+        return;
+      }
+      const step = event.shiftKey ? COARSE_STEP : STEP;
+      const rect = options.rect();
+      let moved: { left: number; top: number } | null = null;
+      if (event.key === "ArrowLeft") {
+        moved = { left: rect.left - step, top: rect.top };
+      } else if (event.key === "ArrowRight") {
+        moved = { left: rect.left + step, top: rect.top };
+      } else if (event.key === "ArrowUp") {
+        moved = { left: rect.left, top: rect.top - step };
+      } else if (event.key === "ArrowDown") {
+        moved = { left: rect.left, top: rect.top + step };
+      }
+      if (moved === null) {
+        return;
+      }
+      event.preventDefault();
+      const next = clampLauncher({ ...rect, ...moved }, options.viewport());
+      // Live feedback per key event, persistence only when the gesture ends: a
+      // held arrow repeats at the OS rate, and committing here would put that
+      // many storage writes behind a single press.
+      options.apply(next.left, next.top);
+      pending = next;
+    },
+    { signal },
+  );
 
   // The key coming up ends the gesture, mirroring `pointerup`. `blur` closes
   // one whose keyup never arrives here -- focus moved on mid-press -- because a
   // position applied but never committed is a move the host silently forgets.
-  launcher.addEventListener("keyup", settle);
-  launcher.addEventListener("blur", settle);
+  launcher.addEventListener("keyup", settle, { signal });
+  launcher.addEventListener("blur", settle, { signal });
 }