@carlonicora/nextjs-jsonapi 3.23.0 → 3.24.1

package/src/features/assistant/components/containers/__tests__/AssistantContainer.spec.tsx

@@ -3,7 +3,23 @@ vi.mock("../../../../../contexts/SocketContext", () => ({
 }));
 
 vi.mock("../../../../../components/containers/RoundPageContainer", () => ({
-  RoundPageContainer: ({ children }: { children: React.ReactNode }) => <>{children}</>,
+  RoundPageContainer: ({
+    children,
+    details,
+    detailsTitle,
+  }: {
+    children: React.ReactNode;
+    details?: React.ReactNode;
+    detailsTitle?: React.ReactNode;
+  }) => (
+    <div data-testid="round-page-container">
+      {children}
+      <div data-testid="round-page-details">
+        {detailsTitle}
+        {details}
+      </div>
+    </div>
+  ),
 }));
 
 import { describe, it, expect, vi, beforeAll, beforeEach } from "vitest";
@@ -13,11 +29,40 @@ import { AssistantService } from "../../../data/AssistantService";
 import type { JsonApiHydratedDataInterface } from "../../../../../core";
 import { AssistantContainer } from "../AssistantContainer";
 import { ModuleRegistry } from "../../../../../core/registry/ModuleRegistry";
+import { configureI18n } from "../../../../../i18n";
 import { DataClassRegistry } from "../../../../../core/registry/DataClassRegistry";
 import { Assistant } from "../../../data/Assistant";
 import { AssistantMessage } from "../../../../assistant-message/data/AssistantMessage";
 
 beforeAll(() => {
+  // The package Link resolves its inner component at runtime and throws if i18n
+  // was never configured (src/i18n/config.ts).
+  configureI18n({
+    useRouter: () => ({
+      push: vi.fn(),
+      replace: vi.fn(),
+      back: vi.fn(),
+      forward: vi.fn(),
+      refresh: vi.fn(),
+      prefetch: vi.fn(),
+    }),
+    useTranslations: () => (key: string) => key,
+    usePathname: () => "/",
+    Link: ({
+      href,
+      children,
+      prefetch: _prefetch,
+      ...rest
+    }: {
+      href: string;
+      children: React.ReactNode;
+      [key: string]: any;
+    }) => (
+      <a href={href} {...rest}>
+        {children}
+      </a>
+    ),
+  });
   Element.prototype.scrollIntoView = vi.fn();
   const assistantModule = { name: "assistants", model: Assistant } as any;
   const assistantMessageModule = { name: "assistant-messages", model: AssistantMessage } as any;
@@ -25,6 +70,7 @@ beforeAll(() => {
   DataClassRegistry.registerObjectClass(assistantMessageModule, AssistantMessage);
   ModuleRegistry.register("Assistant" as any, assistantModule as any);
   ModuleRegistry.register("AssistantMessage" as any, assistantMessageModule as any);
+  ModuleRegistry.register("Npc" as any, { name: "npcs", pageUrl: "/npcs" } as any);
 });
 
 beforeEach(() => {
@@ -48,6 +94,17 @@ function buildAssistantDehydrated({
   };
 }
 
+function buildMessageDehydrated({ id, content }: { id: string; content: string }): JsonApiHydratedDataInterface {
+  return {
+    jsonApi: {
+      type: "assistant-messages",
+      id,
+      attributes: { role: "user", content, position: 1 },
+    },
+    included: [],
+  };
+}
+
 describe("AssistantContainer", () => {
   it("shows empty state when no assistant is active", async () => {
     render(
@@ -98,4 +155,109 @@ describe("AssistantContainer", () => {
     // Status line is showing ("thinking…" translation key renders literally in tests).
     expect(screen.getByText("features.assistant.thinking")).toBeInTheDocument();
   });
+
+  it("passes renderMention through to messages", () => {
+    const active = buildAssistantDehydrated({ id: "a1", title: "T" });
+    const messages = [buildMessageDehydrated({ id: "m1", content: "Ask [X](mention://npcs/n1) about it." })];
+    render(
+      <AssistantProvider dehydratedAssistant={active} dehydratedMessages={messages}>
+        <AssistantContainer
+          renderMention={({ type, id, alias }) => <span data-testid="custom-mention">{`${type}:${id}:${alias}`}</span>}
+        />
+      </AssistantProvider>,
+    );
+    expect(screen.getByTestId("custom-mention")).toHaveTextContent("npcs:n1:X");
+  });
+
+  it("uses EntityMentionLink by default", () => {
+    const active = buildAssistantDehydrated({ id: "a1", title: "T" });
+    const messages = [buildMessageDehydrated({ id: "m1", content: "Ask [X](mention://npcs/n1) about it." })];
+    render(
+      <AssistantProvider dehydratedAssistant={active} dehydratedMessages={messages}>
+        <AssistantContainer />
+      </AssistantProvider>,
+    );
+    expect(screen.getByRole("link", { name: "X" })).toHaveAttribute("href", "/npcs/n1");
+  });
+
+  it("embedded renders without RoundPageContainer", async () => {
+    const { unmount } = render(
+      <AssistantProvider>
+        <AssistantContainer />
+      </AssistantProvider>,
+    );
+    expect(screen.getByTestId("round-page-container")).toBeInTheDocument();
+    unmount();
+
+    render(
+      <AssistantProvider>
+        <AssistantContainer embedded />
+      </AssistantProvider>,
+    );
+    await waitFor(() =>
+      expect(screen.getByRole("heading", { name: "features.assistant.empty_state.title" })).toBeInTheDocument(),
+    );
+    expect(screen.queryByTestId("round-page-container")).not.toBeInTheDocument();
+  });
+
+  it("renderScopePicker shows only before the first message", async () => {
+    AssistantService.create = vi.fn().mockImplementation(() => new Promise(() => {}));
+
+    render(
+      <AssistantProvider>
+        <AssistantContainer renderScopePicker={() => <div data-testid="scope-picker" />} />
+      </AssistantProvider>,
+    );
+    expect(screen.getByTestId("scope-picker")).toBeInTheDocument();
+
+    const textarea = await screen.findByRole("textbox");
+    const user = (await import("@testing-library/user-event")).default.setup();
+    await user.type(textarea, "first one");
+    await user.keyboard("{Enter}");
+
+    await waitFor(() => expect(screen.queryByTestId("scope-picker")).not.toBeInTheDocument());
+  });
+
+  it("shows the operator toggle by default", async () => {
+    render(
+      <AssistantProvider>
+        <AssistantContainer />
+      </AssistantProvider>,
+    );
+    await waitFor(() => expect(screen.getByText("features.assistant.operator_mode")).toBeInTheDocument());
+  });
+
+  it("showOperatorToggle={false} hides the operator toggle", async () => {
+    render(
+      <AssistantProvider>
+        <AssistantContainer showOperatorToggle={false} />
+      </AssistantProvider>,
+    );
+    await waitFor(() =>
+      expect(screen.getByRole("heading", { name: "features.assistant.empty_state.title" })).toBeInTheDocument(),
+    );
+    expect(screen.queryByText("features.assistant.operator_mode")).not.toBeInTheDocument();
+  });
+
+  it("page: thread list sits in the details panel, without its own new button", async () => {
+    AssistantService.findMany = vi.fn().mockResolvedValue([]);
+    render(
+      <AssistantProvider>
+        <AssistantContainer />
+      </AssistantProvider>,
+    );
+    const details = screen.getByTestId("round-page-details");
+    expect(details).toHaveTextContent("features.assistant.list_title");
+    await waitFor(() => expect(details).toHaveTextContent("features.assistant.empty_sidebar"));
+    expect(screen.queryByRole("button", { name: /features\.assistant\.new/ })).not.toBeInTheDocument();
+  });
+
+  it("embedded: keeps the sidebar with its new button", async () => {
+    render(
+      <AssistantProvider>
+        <AssistantContainer embedded />
+      </AssistantProvider>,
+    );
+    expect(screen.getByRole("button", { name: /features\.assistant\.new/ })).toBeInTheDocument();
+  });
 });

package/src/features/assistant/components/parts/AssistantComposer.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useState, type KeyboardEvent } from "react";
+import { useState, type KeyboardEvent, type ReactNode } from "react";
 import { useTranslations } from "next-intl";
 import { ArrowUp } from "lucide-react";
 import { Button, Textarea } from "../../../../shadcnui";
@@ -22,6 +22,11 @@ interface Props {
    * move.
    */
   sendLabel?: string;
+  /**
+   * Rendered at the bottom-left of the input box, opposite the send button
+   * (e.g. a scope picker). When omitted the box keeps its single-row layout.
+   */
+  leading?: ReactNode;
 }
 
 export function AssistantComposer({
@@ -31,6 +36,7 @@ export function AssistantComposer({
   onValueChange,
   placeholder,
   sendLabel,
+  leading,
 }: Props) {
   const t = useTranslations();
   const [internal, setInternal] = useState("");
@@ -53,22 +59,39 @@ export function AssistantComposer({
     }
   };
 
+  const textarea = (
+    <Textarea
+      value={value}
+      onChange={(e) => setValue(e.target.value)}
+      onKeyDown={onKeyDown}
+      placeholder={placeholder ?? t("features.assistant.composer_placeholder")}
+      disabled={disabled}
+      rows={2}
+      className="min-h-[48px] resize-none border-0 bg-transparent focus-visible:ring-0"
+    />
+  );
+  const sendButton = (
+    <Button onClick={submit} disabled={!canSend} size="sm" className="h-8">
+      <ArrowUp className="me-1 h-4 w-4" /> {sendLabel ?? t("features.assistant.send")}
+    </Button>
+  );
+
   return (
     <div className="flex flex-col gap-1 border-t p-4">
-      <div className="bg-muted/30 flex items-end gap-2 rounded-lg border p-2">
-        <Textarea
-          value={value}
-          onChange={(e) => setValue(e.target.value)}
-          onKeyDown={onKeyDown}
-          placeholder={placeholder ?? t("features.assistant.composer_placeholder")}
-          disabled={disabled}
-          rows={2}
-          className="min-h-[48px] resize-none border-0 bg-transparent focus-visible:ring-0"
-        />
-        <Button onClick={submit} disabled={!canSend} size="sm" className="h-8">
-          <ArrowUp className="me-1 h-4 w-4" /> {sendLabel ?? t("features.assistant.send")}
-        </Button>
-      </div>
+      {leading ? (
+        <div className="bg-muted/30 flex flex-col gap-2 rounded-lg border p-2">
+          {textarea}
+          <div className="flex items-center justify-between gap-2">
+            <div className="min-w-0">{leading}</div>
+            {sendButton}
+          </div>
+        </div>
+      ) : (
+        <div className="bg-muted/30 flex items-end gap-2 rounded-lg border p-2">
+          {textarea}
+          {sendButton}
+        </div>
+      )}
       <div className="text-muted-foreground text-end text-xs">{t("features.assistant.keyboard_hint")}</div>
     </div>
   );

package/src/features/assistant/components/parts/AssistantEmptyState.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useState } from "react";
+import { useState, type ReactNode } from "react";
 import { useTranslations } from "next-intl";
 import { Sparkles } from "lucide-react";
 import { Label, Switch } from "../../../../shadcnui";
@@ -16,11 +16,13 @@ interface Props {
    */
   operatorMode?: boolean;
   onOperatorModeChange?: (value: boolean) => void;
+  /** Rendered inside the composer, bottom-left (e.g. a scope picker). */
+  composerLeading?: ReactNode;
 }
 
 const STARTER_KEYS = ["a", "b", "c", "d"] as const;
 
-export function AssistantEmptyState({ onSend, operatorMode = false, onOperatorModeChange }: Props) {
+export function AssistantEmptyState({ onSend, operatorMode = false, onOperatorModeChange, composerLeading }: Props) {
   const t = useTranslations();
   const [draft, setDraft] = useState("");
 
@@ -34,7 +36,7 @@ export function AssistantEmptyState({ onSend, operatorMode = false, onOperatorMo
           <SectionHeader>{t("features.assistant.empty_state.title")}</SectionHeader>
           <p className="text-muted-foreground mt-1 text-sm">{t("features.assistant.empty_state.subtitle")}</p>
         </div>
-        <AssistantComposer value={draft} onValueChange={setDraft} onSend={onSend} />
+        <AssistantComposer value={draft} onValueChange={setDraft} onSend={onSend} leading={composerLeading} />
         {onOperatorModeChange && (
           <div className="flex items-center justify-end gap-2">
             <Switch

package/src/features/assistant/components/parts/AssistantSidebar.tsx

@@ -2,6 +2,7 @@
 
 import { useTranslations } from "next-intl";
 import { Plus } from "lucide-react";
+import type { ReactNode } from "react";
 import { Button } from "../../../../shadcnui";
 import { MicroLabel } from "../../../../components/typography";
 import type { AssistantInterface } from "../../data/AssistantInterface";
@@ -11,7 +12,12 @@ interface Props {
   threads: AssistantInterface[];
   activeId?: string;
   onSelect: (id: string) => void;
-  onNew: () => void;
+  /**
+   * Starts a new thread. Omit it when the host renders the "new" action
+   * elsewhere (the `/assistants` page puts it in the page header), and the
+   * sidebar then shows only the thread list.
+   */
+  onNew?: () => void;
   /**
    * Label of the "start a new thread" button. Defaults to the assistant's own
    * copy; a surface that is not the assistant (the handbook chat) passes its
@@ -20,9 +26,19 @@ interface Props {
   newLabel?: string;
   /** Shown when there are no threads. Same rationale as `newLabel`. */
   emptyLabel?: string;
+  /** Optional badge rendered inside each thread button, after the title (e.g. the thread's scope). */
+  renderThreadBadge?: (thread: AssistantInterface) => ReactNode;
 }
 
-export function AssistantSidebar({ threads, activeId, onSelect, onNew, newLabel, emptyLabel }: Props) {
+export function AssistantSidebar({
+  threads,
+  activeId,
+  onSelect,
+  onNew,
+  newLabel,
+  emptyLabel,
+  renderThreadBadge,
+}: Props) {
   const t = useTranslations();
   const groups = groupThreadsByBucket(threads);
 
@@ -42,6 +58,7 @@ export function AssistantSidebar({ threads, activeId, onSelect, onNew, newLabel,
             }
           >
             {thread.title}
+            {renderThreadBadge?.(thread)}
           </button>
         ))}
       </div>
@@ -50,11 +67,13 @@ export function AssistantSidebar({ threads, activeId, onSelect, onNew, newLabel,
 
   return (
     <aside className="bg-muted/30 flex w-64 flex-col border-e">
-      <div className="border-b p-3">
-        <Button onClick={onNew} className="w-full" size="sm">
-          <Plus className="me-1 h-4 w-4" /> {newLabel ?? t("features.assistant.new")}
-        </Button>
-      </div>
+      {onNew && (
+        <div className="border-b p-3">
+          <Button onClick={onNew} className="w-full" size="sm">
+            <Plus className="me-1 h-4 w-4" /> {newLabel ?? t("features.assistant.new")}
+          </Button>
+        </div>
+      )}
       <div className="flex-1 overflow-y-auto p-2">
         {threads.length === 0 ? (
           <div className="text-muted-foreground mt-6 text-center text-xs">

package/src/features/assistant/components/parts/__tests__/AssistantComposer.spec.tsx

@@ -29,4 +29,12 @@ describe("AssistantComposer", () => {
     const send = screen.getByRole("button", { name: /features\.assistant\.send/i });
     expect(send).toBeDisabled();
   });
+
+  it("renders the leading slot inside the input box, before the send button", () => {
+    render(<AssistantComposer onSend={vi.fn()} leading={<span data-testid="leading-slot" />} />);
+    const slot = screen.getByTestId("leading-slot");
+    const send = screen.getByRole("button", { name: /features\.assistant\.send/i });
+    expect(slot.compareDocumentPosition(send) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
+    expect(slot.closest(".rounded-lg")).toBe(send.closest(".rounded-lg"));
+  });
 });

package/src/features/assistant/components/parts/__tests__/AssistantSidebar.spec.tsx

@@ -55,4 +55,11 @@ describe("AssistantSidebar", () => {
     await userEvent.click(screen.getByRole("button", { name: /^T$/ }));
     expect(onSelect).toHaveBeenCalledWith("a1");
   });
+
+  it("without onNew renders no new button", () => {
+    const threads = [buildAssistantStub({ id: "a1", title: "T", updatedAt: new Date("2026-04-22T09:00:00Z") })];
+    render(<AssistantSidebar threads={threads} onSelect={vi.fn()} />);
+    expect(screen.queryByRole("button", { name: /features\.assistant\.new/ })).not.toBeInTheDocument();
+    expect(screen.getByRole("button", { name: /^T$/ })).toBeInTheDocument();
+  });
 });

package/src/features/assistant/contexts/AssistantContext.tsx

@@ -1,8 +1,10 @@
 "use client";
 
+import { PlusCircleIcon } from "lucide-react";
 import { useTranslations } from "next-intl";
 import React, { createContext, useCallback, useContext, useEffect, useMemo, useState } from "react";
 import { SharedProvider } from "../../../contexts";
+import { Button } from "../../../shadcnui";
 import { useSocketContext } from "../../../contexts/SocketContext";
 import { BreadcrumbItemData, JsonApiHydratedDataInterface, Modules, rehydrate, rehydrateList } from "../../../core";
 import { usePageUrlGenerator } from "../../../hooks";
@@ -40,6 +42,10 @@ interface AssistantContextValue {
   setOperatorMode(value: boolean): void;
   /** Appends a message returned outside the send flow (e.g. an approve/deny resume). */
   appendResolvedMessage(message: AssistantMessageInterface): void;
+  /** The scope a NEW thread will bind to. Starts from the provider's `scope` prop. */
+  scope?: { type: string; id: string };
+  /** Changes the scope a new thread binds to. Ignored once a thread is active. */
+  setScope(scope?: { type: string; id: string }): void;
 }
 
 const AssistantContext = createContext<AssistantContextValue | undefined>(undefined);
@@ -141,6 +147,9 @@ export function AssistantProvider({
   const [operatorMode, setOperatorMode] = useState<boolean>(
     () => dehydratedAssistant?.jsonApi?.attributes?.engine === "operator",
   );
+  // The scope the next created thread binds to. Starts from the `scope` prop
+  // and can be changed by the host (e.g. a scope picker) until a thread exists.
+  const [pendingScope, setPendingScope] = useState<{ type: string; id: string } | undefined>(scope);
   const { socket } = useSocketContext();
 
   const sendMessage = useCallback(
@@ -172,6 +181,35 @@ export function AssistantProvider({
       };
       socket?.on("assistant:status", handler);
 
+      // A new thread is named and persisted before its answer runs; the server
+      // announces it on `assistant:created` so the thread list and the URL
+      // update immediately instead of when the long create request returns.
+      let createdHandled = false;
+      const createdHandler = (payload: {
+        assistant?: { data?: JsonApiHydratedDataInterface["jsonApi"]; included?: any[] };
+      }) => {
+        if (createdHandled) return;
+        const data = payload?.assistant?.data;
+        if (!data || typeof data !== "object" || typeof data.id !== "string" || !data.id) return;
+        let thread: AssistantInterface;
+        try {
+          thread = rehydrate<AssistantInterface>(Modules.Assistant, {
+            jsonApi: data,
+            included: payload.assistant?.included ?? [],
+          });
+        } catch {
+          return;
+        }
+        if (!thread?.id) return;
+        createdHandled = true;
+        setAssistant(thread);
+        setThreads((prev) => [thread, ...prev.filter((row) => row.id !== thread.id)]);
+        if (manageUrl && typeof window !== "undefined") {
+          window.history.replaceState(null, "", resolveThreadUrl(thread.id));
+        }
+      };
+      if (!assistant) socket?.on("assistant:created", createdHandler);
+
       try {
         if (!assistant) {
           const input = {
@@ -181,7 +219,7 @@ export function AssistantProvider({
             handbookMode: opts?.handbookMode ?? retrievalMode?.handbookMode,
             limitToHandbookPageId: opts?.limitToHandbookPageId ?? retrievalMode?.limitToHandbookPageId,
             contentBlocks: opts?.contentBlocks,
-            boundContent: scope,
+            boundContent: pendingScope,
           };
           const created = operatorMode
             ? await AssistantService.createOperator(input)
@@ -189,7 +227,11 @@ export function AssistantProvider({
           const msgs = await AssistantMessageService.findByAssistant({ assistantId: created.id });
           setAssistant(created);
           setMessages(msgs);
-          setThreads((prev) => [created, ...prev]);
+          setThreads((prev) =>
+            prev.some((row) => row.id === created.id)
+              ? prev.map((row) => (row.id === created.id ? created : row))
+              : [created, ...prev],
+          );
           if (manageUrl && typeof window !== "undefined") {
             window.history.replaceState(null, "", resolveThreadUrl(created.id));
           }
@@ -219,11 +261,12 @@ export function AssistantProvider({
         });
       } finally {
         socket?.off("assistant:status", handler);
+        if (!assistant) socket?.off("assistant:created", createdHandler);
         setSending(false);
         setStatus(undefined);
       }
     },
-    [assistant, messages, socket, operatorMode, scope, retrievalMode, manageUrl, resolveThreadUrl],
+    [assistant, messages, socket, operatorMode, pendingScope, retrievalMode, manageUrl, resolveThreadUrl],
   );
 
   const appendResolvedMessage = useCallback((message: AssistantMessageInterface) => {
@@ -278,10 +321,20 @@ export function AssistantProvider({
     setMessages([]);
     setFailedMessageIds(new Set());
     setOperatorMode(false);
+    setPendingScope(scope);
     if (manageUrl && typeof window !== "undefined") {
       window.history.replaceState(null, "", resolveThreadUrl());
     }
-  }, [manageUrl, resolveThreadUrl]);
+  }, [manageUrl, resolveThreadUrl, scope]);
+
+  const setScope = useCallback(
+    (next?: { type: string; id: string }) => {
+      // An existing thread is already bound; its scope cannot change.
+      if (assistant) return;
+      setPendingScope(next);
+    },
+    [assistant],
+  );
 
   const deleteThread = useCallback(async (id: string) => {
     await AssistantService.delete({ id });
@@ -329,6 +382,8 @@ export function AssistantProvider({
       operatorMode,
       setOperatorMode,
       appendResolvedMessage,
+      scope: pendingScope,
+      setScope,
     }),
     [
       assistant,
@@ -346,6 +401,8 @@ export function AssistantProvider({
       deleteThread,
       operatorMode,
       appendResolvedMessage,
+      pendingScope,
+      setScope,
     ],
   );
 
@@ -360,9 +417,36 @@ export function AssistantProvider({
 
   // `entities.tasks` was a copy-paste from another feature and rendered
   // "Tasks" as the page heading of every assistant page.
-  const title = {
-    type: titleOverride ?? t("entities.assistants", { count: 2 }),
-  };
+  // Shaped like the conversations page heading: the open thread's title as the
+  // element, and the new-thread action in the shared header so it stays
+  // reachable when the thread-list panel is collapsed.
+  const title = useMemo(() => {
+    const response: { type: string; element?: string; functions?: React.ReactNode } = {
+      type: titleOverride ?? t("entities.assistants", { count: assistant ? 1 : 2 }),
+    };
+
+    if (assistant?.title) {
+      response.element = assistant.title.length > 25 ? `${assistant.title.substring(0, 25)}...` : assistant.title;
+    }
+
+    response.functions = [
+      <Button
+        key="new-assistant"
+        data-testid="assistant-new-button"
+        size="sm"
+        variant={`outline`}
+        onClick={(e) => {
+          e.preventDefault();
+          startNew();
+        }}
+      >
+        <PlusCircleIcon className="me-2 h-3.5 w-3.5" />
+        {t("features.assistant.new")}
+      </Button>,
+    ];
+
+    return response;
+  }, [assistant, startNew, t, titleOverride]);
 
   return (
     <AssistantContext.Provider value={value}>