@agent-native/toolkit 0.201.1 → 0.201.2-nightly-20261006010750

package/src/app/i18n/catalogs/fr-FR.ts

@@ -922,6 +922,9 @@ const messages: ToolkitAgentChatTranslation = {
   "tool.failedWithoutDetails": "Aucun détail d’erreur disponible.",
   "tool.input": "Entrée",
   "tool.inputWithLabel": "Entrée - {{label}}",
+  "tool.identifierHidden": "[Identifiant masqué]",
+  "tool.contentOmitted": "[Contenu omis]",
+  "tool.circularReference": "[Référence circulaire]",
   "tool.interrupted":
     "Interrompu avant la confirmation de la fin de l’opération ; celle-ci a peut-être abouti ou non. Vérifiez avant de réessayer.",
   "tool.longRunning":

package/src/app/i18n/catalogs/hi-IN.ts

@@ -1271,6 +1271,9 @@ const messages: ToolkitAgentChatTranslation = {
   "tool.failedWithoutDetails": "त्रुटि का कोई विवरण उपलब्ध नहीं है।",
   "tool.input": "इनपुट",
   "tool.inputWithLabel": "इनपुट - {{label}}",
+  "tool.identifierHidden": "[पहचानकर्ता छिपाया गया]",
+  "tool.contentOmitted": "[सामग्री छोड़ी गई]",
+  "tool.circularReference": "[चक्रीय संदर्भ]",
   "tool.interrupted":
     "रिपोर्ट पूरी होने से पहले प्रक्रिया रुक गई — संभव है कि कार्य पूरा हुआ हो या न हुआ हो। दोबारा प्रयास करने से पहले जाँच लें।",
   "tool.longRunning": "काम अभी जारी है। बड़े अपडेट में एक-दो मिनट लग सकते हैं।",

package/src/app/i18n/catalogs/ja-JP.ts

@@ -1306,6 +1306,9 @@ const messages: ToolkitAgentChatTranslation = {
   "tool.failedWithoutDetails": "エラーの詳細はありません。",
   "tool.input": "入力",
   "tool.inputWithLabel": "入力 - {{label}}",
+  "tool.identifierHidden": "[識別子を非表示]",
+  "tool.contentOmitted": "[内容を省略]",
+  "tool.circularReference": "[循環参照]",
   "tool.interrupted":
     "完了報告の前に中断されました。処理は完了している場合も、していない場合もあります。再試行する前に確認してください。",
   "tool.longRunning":

package/src/app/i18n/catalogs/ko-KR.ts

@@ -1285,6 +1285,9 @@ const messages: ToolkitAgentChatTranslation = {
   "tool.failedWithoutDetails": "오류 세부 정보가 없습니다.",
   "tool.input": "입력",
   "tool.inputWithLabel": "입력 - {{label}}",
+  "tool.identifierHidden": "[식별자 숨김]",
+  "tool.contentOmitted": "[내용 생략]",
+  "tool.circularReference": "[순환 참조]",
   "tool.interrupted":
     "완료 보고 전에 중단되었습니다. 작업이 완료되었을 수도 있고 아닐 수도 있습니다. 다시 시도하기 전에 확인하세요.",
   "tool.longRunning":

package/src/app/i18n/catalogs/pt-BR.ts

@@ -909,6 +909,9 @@ const messages: ToolkitAgentChatTranslation = {
   "tool.failedWithoutDetails": "Nenhum detalhe do erro disponível.",
   "tool.input": "Entrada",
   "tool.inputWithLabel": "Entrada - {{label}}",
+  "tool.identifierHidden": "[Identificador oculto]",
+  "tool.contentOmitted": "[Conteúdo omitido]",
+  "tool.circularReference": "[Referência circular]",
   "tool.interrupted":
     "Interrompido antes da confirmação da conclusão — a operação pode ou não ter sido concluída. Verifique antes de tentar novamente.",
   "tool.longRunning":

package/src/app/i18n/catalogs/zh-CN.ts

@@ -1218,6 +1218,9 @@ const messages: ToolkitAgentChatTranslation = {
   "tool.failedWithoutDetails": "没有可用的错误详情。",
   "tool.input": "输入",
   "tool.inputWithLabel": "输入 - {{label}}",
+  "tool.identifierHidden": "[标识符已隐藏]",
+  "tool.contentOmitted": "[内容已省略]",
+  "tool.circularReference": "[循环引用]",
   "tool.interrupted":
     "在完成报告前被中断——操作可能已经完成，也可能尚未完成。重试前请先检查。",
   "tool.longRunning": "仍在处理。大型更新可能需要一两分钟。",

package/src/app/i18n/catalogs/zh-TW.ts

@@ -1222,6 +1222,9 @@ const messages: ToolkitAgentChatTranslation = {
   "tool.failedWithoutDetails": "沒有可用的錯誤詳細資料。",
   "tool.input": "輸入",
   "tool.inputWithLabel": "輸入 - {{label}}",
+  "tool.identifierHidden": "[識別碼已隱藏]",
+  "tool.contentOmitted": "[內容已省略]",
+  "tool.circularReference": "[循環參照]",
   "tool.interrupted":
     "在完成回報前遭到中斷——操作可能已完成，也可能尚未完成。重試前請先檢查。",
   "tool.longRunning": "仍在處理。大型更新可能需要一兩分鐘。",

package/src/composer/AgentSuggestionBar.overflow.spec.tsx

@@ -0,0 +1,277 @@
+// @vitest-environment happy-dom
+
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import type { ActionButtonProps } from "../design-system/types.js";
+import { ToolkitProvider } from "../provider.js";
+import { AgentSuggestionBar } from "./AgentSuggestionBar.js";
+
+const DOCUMENT_SUGGESTIONS = [
+  "Summarize this document",
+  "Improve this document",
+  "Find the action items",
+];
+const CHIP_WIDTHS: Record<string, number> = {
+  "Summarize this document": 155,
+  "Improve this document": 144,
+  "Find the action items": 144,
+};
+// A 280px agent panel minus the bar's and scroller's inline padding.
+const NARROWEST_SCROLLER_WIDTH = 252;
+
+describe("AgentSuggestionBar overflow", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+  let gapStyle: HTMLStyleElement;
+  let scrollerWidth: number;
+  let scrollOffset: number;
+  let resizeCallbacks: Array<() => void>;
+  let disconnectObserver: ReturnType<typeof vi.fn>;
+  const descriptors = new Map<string, PropertyDescriptor | undefined>();
+
+  const scroller = () =>
+    container.querySelector<HTMLElement>(
+      '[data-agent-suggestion-scroller="true"]',
+    )!;
+  const track = () =>
+    container.querySelector<HTMLElement>(
+      '[data-agent-suggestion-track="true"]',
+    )!;
+  const trackWidth = () =>
+    Number.parseFloat(
+      track().style.getPropertyValue("--agent-suggestion-track-width"),
+    );
+  const fadeEdges = () => ({
+    start: scroller().getAttribute("data-overflow-start"),
+    end: scroller().getAttribute("data-overflow-end"),
+  });
+
+  function defineLayout(name: string, descriptor: PropertyDescriptor) {
+    descriptors.set(
+      name,
+      Object.getOwnPropertyDescriptor(HTMLElement.prototype, name),
+    );
+    Object.defineProperty(HTMLElement.prototype, name, {
+      configurable: true,
+      ...descriptor,
+    });
+  }
+
+  function render(suggestions: string[]) {
+    act(() => {
+      root.render(
+        <AgentSuggestionBar
+          ariaLabel="Suggested prompts"
+          suggestions={suggestions}
+          onSelect={() => {}}
+        />,
+      );
+    });
+  }
+
+  function resizeScroller(width: number) {
+    scrollerWidth = width;
+    act(() => resizeCallbacks.forEach((callback) => callback()));
+  }
+
+  function scrollTo(offset: number) {
+    scrollOffset = offset;
+    act(() => {
+      scroller().dispatchEvent(new Event("scroll"));
+    });
+  }
+
+  beforeEach(() => {
+    vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+    scrollerWidth = NARROWEST_SCROLLER_WIDTH;
+    scrollOffset = 0;
+    resizeCallbacks = [];
+    disconnectObserver = vi.fn();
+    vi.stubGlobal(
+      "ResizeObserver",
+      class {
+        constructor(callback: () => void) {
+          resizeCallbacks.push(callback);
+        }
+        observe() {}
+        disconnect = disconnectObserver;
+      },
+    );
+    vi.stubGlobal("requestAnimationFrame", (callback: FrameRequestCallback) => {
+      callback(0);
+      return 1;
+    });
+    vi.stubGlobal("cancelAnimationFrame", () => {});
+
+    gapStyle = document.createElement("style");
+    gapStyle.textContent =
+      '[data-agent-suggestion-track="true"] { column-gap: 4px; }';
+    document.head.appendChild(gapStyle);
+
+    defineLayout("getBoundingClientRect", {
+      value(this: HTMLElement) {
+        const width = CHIP_WIDTHS[this.textContent ?? ""] ?? 0;
+        return { width, height: 28, top: 0, left: 0, right: width, bottom: 28 };
+      },
+    });
+    defineLayout("clientWidth", {
+      get(this: HTMLElement) {
+        return this.dataset.agentSuggestionScroller ? scrollerWidth : 0;
+      },
+    });
+    defineLayout("scrollWidth", {
+      get(this: HTMLElement) {
+        if (!this.dataset.agentSuggestionScroller) return 0;
+        return Math.max(scrollerWidth, trackWidth());
+      },
+    });
+    defineLayout("scrollLeft", {
+      get() {
+        return scrollOffset;
+      },
+      set(value: number) {
+        scrollOffset = value;
+      },
+    });
+
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    gapStyle.remove();
+    for (const [name, descriptor] of descriptors) {
+      if (descriptor) {
+        Object.defineProperty(HTMLElement.prototype, name, descriptor);
+      } else {
+        delete (HTMLElement.prototype as unknown as Record<string, unknown>)[
+          name
+        ];
+      }
+    }
+    descriptors.clear();
+    vi.unstubAllGlobals();
+  });
+
+  it("wraps document suggestions onto two lines at the narrowest panel", () => {
+    render(DOCUMENT_SUGGESTIONS);
+
+    expect(
+      [...container.querySelectorAll("button")].map(
+        (button) => button.textContent,
+      ),
+    ).toEqual(DOCUMENT_SUGGESTIONS);
+    expect(track().className).toContain("flex-wrap");
+    expect(track().className).toContain("min-w-full");
+    // The measured width only lays the chips out in two lines once the track
+    // is sized by it; the mocked geometry here cannot show that on its own.
+    expect(track().className).toContain("w-(--agent-suggestion-track-width)");
+    expect(trackWidth()).toBe(144 + 4 + 144);
+    expect(fadeEdges()).toEqual({ start: null, end: "true" });
+  });
+
+  it("fades only the edges that still hide suggestions", () => {
+    render(DOCUMENT_SUGGESTIONS);
+    const hidden = trackWidth() - NARROWEST_SCROLLER_WIDTH;
+
+    scrollTo(hidden / 2);
+    expect(fadeEdges()).toEqual({ start: "true", end: "true" });
+
+    scrollTo(hidden);
+    expect(fadeEdges()).toEqual({ start: "true", end: null });
+  });
+
+  it("drops the fade once a resize lets every suggestion fit", () => {
+    render(DOCUMENT_SUGGESTIONS);
+    expect(fadeEdges().end).toBe("true");
+
+    resizeScroller(480);
+    expect(fadeEdges()).toEqual({ start: null, end: null });
+
+    resizeScroller(NARROWEST_SCROLLER_WIDTH);
+    expect(fadeEdges()).toEqual({ start: null, end: "true" });
+
+    act(() => root.unmount());
+    expect(disconnectObserver).toHaveBeenCalled();
+    root = createRoot(container);
+  });
+
+  it("scrolls a keyboard-focused suggestion out from under the fade", () => {
+    const scrollIntoView = vi.fn();
+    defineLayout("scrollIntoView", { value: scrollIntoView });
+    render(DOCUMENT_SUGGESTIONS);
+    const lastChip = [...container.querySelectorAll("button")].at(-1)!;
+
+    act(() => lastChip.focus());
+
+    expect(scrollIntoView).toHaveBeenCalledWith({
+      block: "nearest",
+      inline: "nearest",
+    });
+  });
+
+  it("reveals a keyboard-focused suggestion rendered by a host's ActionButton", () => {
+    const scrollIntoView = vi.fn();
+    defineLayout("scrollIntoView", { value: scrollIntoView });
+    // Adapters receive only the props Button forwards, which omit onFocus.
+    const HostActionButton = ({
+      label,
+      onClick,
+      elementRef,
+    }: ActionButtonProps) => (
+      <button ref={elementRef} type="button" onClick={onClick}>
+        {label}
+      </button>
+    );
+    act(() => {
+      root.render(
+        <ToolkitProvider
+          designSystem={{ components: { ActionButton: HostActionButton } }}
+        >
+          <AgentSuggestionBar
+            ariaLabel="Suggested prompts"
+            suggestions={DOCUMENT_SUGGESTIONS}
+            onSelect={() => {}}
+          />
+        </ToolkitProvider>,
+      );
+    });
+    const lastChip = [...container.querySelectorAll("button")].at(-1)!;
+
+    act(() => lastChip.focus());
+
+    expect(scrollIntoView).toHaveBeenCalledWith({
+      block: "nearest",
+      inline: "nearest",
+    });
+  });
+
+  it("ships the fade and wrap styles for every host", () => {
+    const styles = readFileSync(
+      path.resolve(
+        path.dirname(fileURLToPath(import.meta.url)),
+        "../app/agentkit/react/styles.css",
+      ),
+      "utf8",
+    ).replace(/\r\n/g, "\n");
+
+    expect(styles).toMatch(
+      /\[data-agent-suggestion-scroller="true"\]:is\(\s*\[data-overflow-start\],\s*\[data-overflow-end\]\s*\) \{[\s\S]*?mask-image: linear-gradient\(/,
+    );
+    expect(styles).toMatch(
+      /\[data-agent-suggestion-scroller="true"\]\[data-overflow-end\] \{\n  --agent-suggestion-fade-end: 1\.5rem;/,
+    );
+    expect(styles).toMatch(
+      /\.agentkit-suggestions \[data-agent-suggestion-track="true"\] \{[\s\S]*?flex-wrap: wrap;[\s\S]*?inline-size: var\(--agent-suggestion-track-width\);[\s\S]*?min-inline-size: 100%;/,
+    );
+  });
+});

package/src/composer/AgentSuggestionBar.tsx

@@ -1,8 +1,18 @@
-import type { ReactNode } from "react";
+import {
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type FocusEvent,
+  type ReactNode,
+} from "react";
 
 import { Button } from "../ui/button.js";
 import { cn } from "../utils.js";
 
+const useBrowserLayoutEffect =
+  typeof window === "undefined" ? useEffect : useLayoutEffect;
+
 export interface AgentSuggestionItem {
   id: string;
   label: string;
@@ -41,6 +51,90 @@ export function agentSuggestionPrompt(
     : (suggestion.prompt ?? suggestion.label);
 }
 
+function twoLineTrackWidth(widths: readonly number[], gap: number): number {
+  const total =
+    widths.reduce((sum, width) => sum + width, 0) +
+    gap * Math.max(widths.length - 1, 0);
+  let narrowest = total;
+  let firstLine = -gap;
+  for (const width of widths.slice(0, -1)) {
+    firstLine += gap + width;
+    narrowest = Math.min(
+      narrowest,
+      Math.max(firstLine, total - firstLine - gap),
+    );
+  }
+  return narrowest;
+}
+
+// Chrome does not scroll a partly visible chip into view when it takes
+// keyboard focus, which leaves it under the edge fade. Listen on the track:
+// a host's ActionButton adapter receives only the props Button forwards, and
+// onFocus is not one of them.
+function revealKeyboardFocusedChip(event: FocusEvent<HTMLDivElement>) {
+  const chip = event.target;
+  if (!(chip instanceof HTMLElement) || !chip.matches(":focus-visible")) return;
+  chip.scrollIntoView({ block: "nearest", inline: "nearest" });
+}
+
+function useTwoLineSuggestionTrack(layoutKey: string) {
+  const scrollerRef = useRef<HTMLDivElement>(null);
+  const trackRef = useRef<HTMLDivElement>(null);
+  const [overflow, setOverflow] = useState({ start: false, end: false });
+
+  useBrowserLayoutEffect(() => {
+    const scroller = scrollerRef.current;
+    const track = trackRef.current;
+    if (!scroller || !track) return;
+    const chips = Array.from(track.children);
+    const updateOverflow = () => {
+      const offset = Math.abs(scroller.scrollLeft);
+      const start = offset > 1;
+      const end = offset + scroller.clientWidth < scroller.scrollWidth - 1;
+      setOverflow((current) =>
+        current.start === start && current.end === end
+          ? current
+          : { start, end },
+      );
+    };
+    const update = () => {
+      const gap = Number.parseFloat(getComputedStyle(track).columnGap);
+      const width = twoLineTrackWidth(
+        chips.map((chip) => chip.getBoundingClientRect().width),
+        Number.isNaN(gap) ? 0 : gap,
+      );
+      track.style.setProperty(
+        "--agent-suggestion-track-width",
+        `${Math.ceil(width)}px`,
+      );
+      updateOverflow();
+    };
+    update();
+
+    // Resizing the track inside the observer callback resizes the observed
+    // scroller in the same frame, which the browser reports as a
+    // ResizeObserver loop error. Measure on the next frame instead.
+    let frame = 0;
+    const observer =
+      typeof ResizeObserver === "undefined"
+        ? null
+        : new ResizeObserver(() => {
+            cancelAnimationFrame(frame);
+            frame = requestAnimationFrame(update);
+          });
+    observer?.observe(scroller);
+    for (const chip of chips) observer?.observe(chip);
+    scroller.addEventListener("scroll", updateOverflow, { passive: true });
+    return () => {
+      cancelAnimationFrame(frame);
+      observer?.disconnect();
+      scroller.removeEventListener("scroll", updateOverflow);
+    };
+  }, [layoutKey]);
+
+  return { scrollerRef, trackRef, overflow };
+}
+
 export function AgentSuggestionBar({
   suggestions,
   ariaLabel,
@@ -48,7 +142,11 @@ export function AgentSuggestionBar({
   renderSuggestion,
   className,
 }: AgentSuggestionBarProps) {
-  if (suggestions.length === 0) return null;
+  const items = suggestions.map(normalizeAgentSuggestion);
+  const { scrollerRef, trackRef, overflow } = useTwoLineSuggestionTrack(
+    items.map((item) => item.id).join("\n"),
+  );
+  if (items.length === 0) return null;
 
   return (
     <section
@@ -57,12 +155,19 @@ export function AgentSuggestionBar({
       className={cn("w-full min-w-0 overflow-hidden px-3 py-2", className)}
     >
       <div
+        ref={scrollerRef}
         data-agent-suggestion-scroller="true"
-        className="flex w-full min-w-0 snap-x snap-proximity gap-1 overflow-x-auto overscroll-x-contain px-0.5 py-px [scrollbar-width:none] [&::-webkit-scrollbar]:hidden"
+        data-overflow-start={overflow.start || undefined}
+        data-overflow-end={overflow.end || undefined}
+        className="w-full min-w-0 snap-x snap-proximity scroll-px-6 overflow-x-auto overscroll-x-contain px-0.5 py-px [scrollbar-width:none] [&::-webkit-scrollbar]:hidden"
       >
-        {suggestions.map((input, index) => {
-          const suggestion = normalizeAgentSuggestion(input, index);
-          return (
+        <div
+          ref={trackRef}
+          data-agent-suggestion-track="true"
+          className="flex w-(--agent-suggestion-track-width) min-w-full flex-wrap gap-1"
+          onFocus={revealKeyboardFocusedChip}
+        >
+          {items.map((suggestion) => (
             <Button
               key={suggestion.id}
               type="button"
@@ -78,8 +183,8 @@ export function AgentSuggestionBar({
                   : suggestion.label}
               </span>
             </Button>
-          );
-        })}
+          ))}
+        </div>
       </div>
     </section>
   );