@runtypelabs/persona 4.17.0 → 4.18.0

package/src/ui.rail-resize.test.ts

@@ -0,0 +1,284 @@
+// @vitest-environment jsdom
+
+/**
+ * Drag-resize of the docked Messages rail
+ * (`features.history.rail.resizable`): where the handle exists, what a drag
+ * and the keyboard do to the width, and how the remembered width is resolved.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { createAgentExperience } from "./ui";
+import { createHistoryView } from "./components/history-view";
+import { setHistoryViewLoader } from "./history-view-loader";
+import { setHistoryProviderFactory } from "./internal/history-provider-registry";
+import {
+  createDemoHistoryProvider,
+  type DemoHistoryConversationSeed,
+} from "./internal/demo-history-provider";
+
+const SEEDS: DemoHistoryConversationSeed[] = [
+  {
+    id: "conv-a",
+    title: "Order status",
+    targetId: null,
+    messages: [{ id: "a1", role: "user", content: "where is my order" }],
+  },
+];
+
+const mounts: HTMLElement[] = [];
+const controllers: ReturnType<typeof createAgentExperience>[] = [];
+
+const flush = async (times = 12) => {
+  for (let i = 0; i < times; i += 1) {
+    // eslint-disable-next-line no-await-in-loop
+    await Promise.resolve();
+  }
+};
+
+const setup = (
+  options: { rail?: Record<string, unknown>; config?: Record<string, unknown> } = {}
+) => {
+  setHistoryProviderFactory(() => createDemoHistoryProvider({ conversations: SEEDS }));
+  const mount = document.createElement("div");
+  document.body.appendChild(mount);
+  mounts.push(mount);
+  const controller = createAgentExperience(mount, {
+    apiUrl: "https://api.example.com/chat",
+    launcher: { enabled: false },
+    persistState: { keyPrefix: "persona-test-" },
+    suggestionChips: [],
+    features: {
+      history: {
+        enabled: true,
+        presentation: "rail",
+        rail: { resizable: true, ...options.rail },
+      },
+    },
+    ...options.config,
+  } as unknown as Parameters<typeof createAgentExperience>[1]);
+  controllers.push(controller);
+  const container = mount.querySelector<HTMLElement>(".persona-widget-container")!;
+  Object.defineProperty(container, "clientWidth", { configurable: true, get: () => 900 });
+  controller.update({});
+  return { mount, controller };
+};
+
+const handleOf = (mount: HTMLElement) =>
+  mount.querySelector<HTMLElement>(".persona-rail-resizer");
+const hostOf = (mount: HTMLElement) =>
+  mount.querySelector<HTMLElement>(".persona-history-rail-host")!;
+const overlayOf = (mount: HTMLElement) =>
+  mount.querySelector<HTMLElement>(".persona-history-rail-overlay");
+const historyButton = (mount: HTMLElement) =>
+  mount.querySelector<HTMLButtonElement>("[data-persona-history-toggle]")!;
+const railToggle = (mount: HTMLElement) =>
+  mount.querySelector<HTMLButtonElement>('[data-persona-history-focus="collapse"]')!;
+const trigger = (mount: HTMLElement) =>
+  mount.querySelector<HTMLButtonElement>("[data-persona-rail-trigger]")!;
+
+/** Opens Messages the way a pointer does. */
+const openRail = async (mount: HTMLElement) => {
+  historyButton(mount).dispatchEvent(
+    new MouseEvent("click", { bubbles: true, cancelable: true, detail: 1 })
+  );
+  await flush();
+};
+
+const press = (element: HTMLElement, key: string) =>
+  element.dispatchEvent(
+    new KeyboardEvent("keydown", { key, bubbles: true, cancelable: true })
+  );
+
+/** A whole drag: press on the handle, travel `dx`, release. */
+const drag = (handle: HTMLElement, dx: number, opts?: { hold?: boolean }) => {
+  handle.dispatchEvent(
+    new MouseEvent("pointerdown", { bubbles: true, cancelable: true, button: 0, clientX: 0 })
+  );
+  document.dispatchEvent(new MouseEvent("pointermove", { clientX: dx }));
+  if (opts?.hold) return;
+  document.dispatchEvent(new MouseEvent("pointerup", { clientX: dx }));
+};
+
+describe("rail resize handle", () => {
+  beforeEach(() => {
+    window.scrollTo = vi.fn();
+    setHistoryViewLoader(async () => ({ createHistoryView }));
+  });
+
+  afterEach(() => {
+    setHistoryProviderFactory(null);
+    controllers.splice(0).forEach((controller) => {
+      try {
+        controller.destroy();
+      } catch {
+        /* already destroyed */
+      }
+    });
+    mounts.splice(0).forEach((mount) => mount.remove());
+    document.body.innerHTML = "";
+    window.localStorage.clear();
+    vi.restoreAllMocks();
+  });
+
+  it("puts a labelled separator on the edge facing the conversation", async () => {
+    const { mount } = setup();
+    await openRail(mount);
+    const handle = handleOf(mount)!;
+    expect(handle).not.toBeNull();
+    expect(handle.getAttribute("role")).toBe("separator");
+    expect(handle.getAttribute("aria-orientation")).toBe("vertical");
+    expect(handle.getAttribute("aria-label")).toBe("Resize conversation list");
+    expect(handle.getAttribute("aria-valuemin")).toBe("200");
+    expect(handle.getAttribute("aria-valuemax")).toBe("400");
+    expect(handle.getAttribute("aria-valuenow")).toBe("260");
+    expect(handle.tabIndex).toBe(0);
+    // Between the rail and the conversation, on the divider's edge.
+    expect(handle.previousElementSibling).toBe(hostOf(mount));
+    expect(handle.nextElementSibling!.className).toContain(
+      "persona-history-rail-conversation"
+    );
+  });
+
+  it("mirrors to the other side of the rail when it docks right", async () => {
+    const { mount } = setup({ rail: { side: "right" } });
+    await openRail(mount);
+    const handle = handleOf(mount)!;
+    expect(handle.nextElementSibling).toBe(hostOf(mount));
+  });
+
+  it("stays out of a rail that was never made resizable", async () => {
+    const { mount } = setup({ rail: { resizable: false } });
+    await openRail(mount);
+    expect(handleOf(mount)).toBeNull();
+  });
+
+  it("leaves the collapsed icon column alone and comes back on expand", async () => {
+    const { mount } = setup();
+    await openRail(mount);
+    railToggle(mount).click();
+    await flush();
+    expect(hostOf(mount).style.flex).toBe("0 0 52px");
+    expect(handleOf(mount)).toBeNull();
+
+    railToggle(mount).click();
+    await flush();
+    expect(handleOf(mount)).not.toBeNull();
+    expect(hostOf(mount).style.flex).toBe("0 0 260px");
+  });
+
+  it("resizes live on drag and commits the width on release", async () => {
+    const { mount } = setup();
+    await openRail(mount);
+    const host = hostOf(mount);
+    const handle = handleOf(mount)!;
+
+    drag(handle, 60, { hold: true });
+    expect(host.style.flex).toBe("0 0 320px");
+    expect(handle.getAttribute("aria-valuenow")).toBe("320");
+    // The collapse transition would trail the pointer for the whole drag.
+    expect(host.style.transition).toBe("none");
+
+    document.dispatchEvent(new MouseEvent("pointerup", { clientX: 60 }));
+    expect(host.style.transition).toBe("");
+    expect(host.style.flex).toBe("0 0 320px");
+    expect(window.localStorage.getItem("persona-test-rail-width")).toBe("320");
+  });
+
+  it("clamps a drag to the rail's own bounds", async () => {
+    const { mount } = setup();
+    await openRail(mount);
+    drag(handleOf(mount)!, 600);
+    expect(hostOf(mount).style.flex).toBe("0 0 400px");
+    expect(window.localStorage.getItem("persona-test-rail-width")).toBe("400");
+
+    drag(handleOf(mount)!, -600);
+    expect(hostOf(mount).style.flex).toBe("0 0 200px");
+    expect(window.localStorage.getItem("persona-test-rail-width")).toBe("200");
+  });
+
+  it("takes arrow steps and jumps to the bounds from the keyboard", async () => {
+    const { mount } = setup();
+    await openRail(mount);
+    const handle = handleOf(mount)!;
+
+    press(handle, "ArrowRight");
+    expect(hostOf(mount).style.flex).toBe("0 0 276px");
+    expect(handle.getAttribute("aria-valuenow")).toBe("276");
+    press(handle, "ArrowLeft");
+    press(handle, "ArrowLeft");
+    expect(hostOf(mount).style.flex).toBe("0 0 244px");
+
+    press(handle, "End");
+    expect(hostOf(mount).style.flex).toBe("0 0 400px");
+    press(handle, "Home");
+    expect(hostOf(mount).style.flex).toBe("0 0 200px");
+    expect(handle.getAttribute("aria-valuenow")).toBe("200");
+    expect(window.localStorage.getItem("persona-test-rail-width")).toBe("200");
+  });
+
+  it("inverts the arrows for a rail docked on the right", async () => {
+    const { mount } = setup({ rail: { side: "right" } });
+    await openRail(mount);
+    // The right rail's edge grows leftward, so the arrows track the pixels.
+    press(handleOf(mount)!, "ArrowLeft");
+    expect(hostOf(mount).style.flex).toBe("0 0 276px");
+  });
+
+  it("keeps a chosen width over config and across a reopen", async () => {
+    const { mount, controller } = setup({ rail: { width: 300 } });
+    await openRail(mount);
+    expect(hostOf(mount).style.flex).toBe("0 0 300px");
+
+    drag(handleOf(mount)!, 40);
+    expect(hostOf(mount).style.flex).toBe("0 0 340px");
+
+    // A live config update must not undo what the visitor chose.
+    controller.update({
+      features: { history: { rail: { width: 220 } } },
+    } as never);
+    await flush();
+    expect(hostOf(mount).style.flex).toBe("0 0 340px");
+
+    historyButton(mount).click();
+    await flush(20);
+    await openRail(mount);
+    expect(hostOf(mount).style.flex).toBe("0 0 340px");
+  });
+
+  it("hands the remembered width to the floating rail, which has no handle", async () => {
+    window.localStorage.setItem("persona-test-rail-width", "340");
+    const { mount } = setup({ rail: { collapsedBehavior: "overlay", defaultCollapsed: true } });
+    trigger(mount).dispatchEvent(new MouseEvent("mouseenter"));
+    await flush();
+    const overlay = overlayOf(mount)!;
+    expect(overlay).not.toBeNull();
+    expect(overlay.style.width).toBe("340px");
+    expect(handleOf(mount)).toBeNull();
+
+    // Pinned, the same width docks, and the handle comes with it.
+    trigger(mount).dispatchEvent(
+      new MouseEvent("click", { bubbles: true, cancelable: true, detail: 1 })
+    );
+    await flush();
+    expect(hostOf(mount).style.flex).toBe("0 0 340px");
+    expect(handleOf(mount)).not.toBeNull();
+  });
+
+  it("stays in memory when state persistence is off", async () => {
+    const setItem = vi.spyOn(Storage.prototype, "setItem");
+    const { mount } = setup({ config: { persistState: false } });
+    await openRail(mount);
+    drag(handleOf(mount)!, 40);
+    expect(hostOf(mount).style.flex).toBe("0 0 300px");
+    expect(
+      setItem.mock.calls.filter(([key]) => String(key).endsWith("rail-width"))
+    ).toEqual([]);
+
+    // The in-memory value still survives a close and reopen.
+    historyButton(mount).click();
+    await flush(20);
+    await openRail(mount);
+    expect(hostOf(mount).style.flex).toBe("0 0 300px");
+  });
+});

package/src/ui.rebuild-composer.test.ts

@@ -345,6 +345,27 @@ describe("rebuildComposer (composer ctx requestRender)", () => {
     expect(mount.style.getPropertyValue("--persona-border")).not.toBe("");
   });
 
+  it("keeps a plugin footer's own inline styles across a rebuild", () => {
+    // applyFullHeightStyles resets footer.style.cssText for the built-in
+    // composer's per-mode geometry. A plugin footer is the plugin's DOM: the
+    // home screen's hidden placeholder relies on inline `display: none`, and
+    // the reset turned it into an empty visible composer band.
+    const plugin: AgentWidgetPlugin = {
+      id: "gate",
+      renderComposer: () => {
+        const footer = document.createElement("div");
+        footer.className = "persona-widget-footer";
+        footer.style.display = "none";
+        footer.setAttribute("data-test-gate", "");
+        return footer;
+      },
+    };
+    const { mount } = makeController({ plugins: [plugin] });
+
+    const footer = mount.querySelector<HTMLElement>("[data-test-gate]")!;
+    expect(footer.style.display).toBe("none");
+  });
+
   it("keeps the floating panel's fixed height across a rebuild", () => {
     // applyFullHeightStyles wipes panel.style.cssText and only restores width;
     // the fixed height belongs to recalcPanelHeight. Without a re-stamp in

package/src/ui.render-welcome.test.ts

@@ -1,5 +1,9 @@
 // @vitest-environment jsdom
 
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
 import { afterEach, describe, expect, it, vi } from "vitest";
 
 import { createAgentExperience } from "./ui";
@@ -256,6 +260,44 @@ describe("renderWelcome plugin hook", () => {
     expect(body.scrollTop).toBe(240);
   });
 
+  it("takes the transcript out of layout while the overlay is mounted", () => {
+    // Zeroing the scroll once at mount does not hold the overlay in place: the
+    // body keeps its own `overflow-y: auto` (inline in fill/fullscreen
+    // layouts, where the overlay state class cannot outrank it), and every
+    // later transcript scroll - autoscroll, a repin, a wheel - drags the
+    // containing block of an `inset: 0` box out from under the viewport. The
+    // plugin stack and the transcript then render as one scrolling column,
+    // with the composer still hidden. Out of layout, nothing scrolls under it.
+    const style = document.createElement("style");
+    style.textContent = readFileSync(
+      resolve(dirname(fileURLToPath(import.meta.url)), "styles/widget.css"),
+      "utf8"
+    );
+    document.head.appendChild(style);
+    let showHome = true;
+    let request: () => void = () => {};
+    const plugin: AgentWidgetPlugin = {
+      id: "home",
+      renderWelcome: (ctx) => {
+        request = ctx.requestRender;
+        if (!showHome) return null;
+        const root = document.createElement("div");
+        root.setAttribute("data-test-home", "");
+        return root;
+      },
+    };
+    const { mount, controller } = makeController({ plugins: [plugin] });
+    controller.injectUserMessage({ content: "hello" });
+
+    const messages = mount.querySelector<HTMLElement>(".persona-widget-messages")!;
+    expect(getComputedStyle(messages).display).toBe("none");
+
+    showHome = false;
+    request();
+    expect(getComputedStyle(messages).display).not.toBe("none");
+    style.remove();
+  });
+
   it("re-enables renderStarter output when a stream ends", async () => {
     const flush = () => new Promise((resolve) => setTimeout(resolve, 0));
     const originalFetch = global.fetch;

package/src/ui.shortcuts.test.ts

@@ -0,0 +1,166 @@
+// @vitest-environment jsdom
+
+/**
+ * Instance-scoped keyboard shortcuts: the header trailing-action surface and
+ * the plugin capability, both bound into the one registry the controller owns.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { createAgentExperience } from "./ui";
+import { setMacPlatformOverride } from "./utils/shortcuts";
+import type { AgentWidgetPlugin } from "./plugins/types";
+
+const controllers: ReturnType<typeof createAgentExperience>[] = [];
+
+const setup = (config: Record<string, unknown>) => {
+  const mount = document.createElement("div");
+  document.body.appendChild(mount);
+  const controller = createAgentExperience(mount, {
+    apiUrl: "https://api.example.com/chat",
+    launcher: { enabled: false },
+    persistState: false,
+    ...config,
+  } as unknown as Parameters<typeof createAgentExperience>[1]);
+  controllers.push(controller);
+  return { mount, controller };
+};
+
+const press = (target: EventTarget, key: string) =>
+  target.dispatchEvent(
+    new KeyboardEvent("keydown", {
+      key,
+      ctrlKey: true,
+      bubbles: true,
+      cancelable: true,
+      composed: true,
+    })
+  );
+
+describe("widget keyboard shortcuts", () => {
+  beforeEach(() => {
+    window.scrollTo = vi.fn();
+    setMacPlatformOverride(false);
+  });
+
+  afterEach(() => {
+    setMacPlatformOverride(null);
+    controllers.splice(0).forEach((controller) => {
+      try {
+        controller.destroy();
+      } catch {
+        /* already destroyed */
+      }
+    });
+    document.body.innerHTML = "";
+    vi.restoreAllMocks();
+  });
+
+  describe("header trailing actions", () => {
+    const withAction = (shortcut?: string) => {
+      const onAction = vi.fn();
+      const { mount, controller } = setup({
+        layout: {
+          header: {
+            layout: "minimal",
+            trailingActions: [
+              {
+                id: "home",
+                icon: "house",
+                ariaLabel: "Back to home",
+                ...(shortcut ? { shortcut } : {}),
+              },
+            ],
+            onAction,
+          },
+        },
+      });
+      return { mount, controller, onAction };
+    };
+
+    it("fires onAction from the declared combo", () => {
+      const { mount, onAction } = withAction("mod+shift+h");
+      const event = new KeyboardEvent("keydown", {
+        key: "h",
+        ctrlKey: true,
+        shiftKey: true,
+        bubbles: true,
+        cancelable: true,
+        composed: true,
+      });
+      mount.dispatchEvent(event);
+      expect(onAction).toHaveBeenCalledWith("home");
+      expect(event.defaultPrevented).toBe(true);
+    });
+
+    it("binds nothing when the action declares no shortcut", () => {
+      const { mount, onAction } = withAction();
+      press(mount, "h");
+      expect(onAction).not.toHaveBeenCalled();
+    });
+
+    it("re-derives the binding from a live update", () => {
+      const { mount, controller, onAction } = withAction();
+      controller.update({
+        layout: {
+          header: {
+            layout: "minimal",
+            trailingActions: [
+              {
+                id: "home",
+                icon: "house",
+                ariaLabel: "Back to home",
+                shortcut: "mod+j",
+              },
+            ],
+          },
+        },
+      } as never);
+      press(mount, "j");
+      expect(onAction).toHaveBeenCalledWith("home");
+    });
+  });
+
+  describe("plugin shortcuts", () => {
+    const plugin = (run: () => void): AgentWidgetPlugin => ({
+      id: "demo",
+      shortcuts: [{ id: "open", combo: "mod+j", run }],
+    });
+
+    it("binds on init and drops on destroy", () => {
+      const run = vi.fn();
+      const { mount, controller } = setup({ plugins: [plugin(run)] });
+      press(mount, "j");
+      expect(run).toHaveBeenCalledTimes(1);
+
+      controller.destroy();
+      press(mount, "j");
+      expect(run).toHaveBeenCalledTimes(1);
+    });
+
+    it("keeps a widget-scoped plugin binding out of the rest of the page", () => {
+      const run = vi.fn();
+      setup({ plugins: [plugin(run)] });
+      const outside = document.createElement("button");
+      document.body.appendChild(outside);
+      press(outside, "j");
+      expect(run).not.toHaveBeenCalled();
+    });
+
+    it("honors an opt-in page scope", () => {
+      const run = vi.fn();
+      setup({
+        plugins: [
+          {
+            id: "demo",
+            shortcuts: [{ id: "open", combo: "mod+j", scope: "page", run }],
+          } as AgentWidgetPlugin,
+        ],
+      });
+      const outside = document.createElement("button");
+      document.body.appendChild(outside);
+      press(outside, "j");
+      expect(run).toHaveBeenCalledTimes(1);
+    });
+  });
+});