@carlonicora/nextjs-jsonapi 3.22.0 → 3.24.0

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

@@ -1,8 +1,13 @@
 "use client";
 
+import { MessagesSquareIcon } from "lucide-react";
+import { useTranslations } from "next-intl";
+import { useMemo, type ReactNode } from "react";
 import { RoundPageContainer } from "../../../../components/containers/RoundPageContainer";
 import { Modules } from "../../../../core";
-import type { ApprovalActionRenderer } from "../../../assistant-message/components/MessageItem";
+import { EntityMentionLink } from "../../../assistant-message/components/EntityMentionLink";
+import type { ApprovalActionRenderer, MentionRenderer } from "../../../assistant-message/components/MessageItem";
+import type { AssistantInterface } from "../../data/AssistantInterface";
 import { useAssistantContext } from "../../contexts/AssistantContext";
 import { AssistantSidebar } from "../parts/AssistantSidebar";
 import { AssistantEmptyState } from "../parts/AssistantEmptyState";
@@ -18,55 +23,119 @@ interface Props {
    * plain markdown bubble.
    */
   renderApprovalAction?: ApprovalActionRenderer;
+  /**
+   * Renderer for `mention://<type>/<id>` links in assistant answers. Defaults
+   * to `EntityMentionLink`, which links registered modules to their page.
+   */
+  renderMention?: MentionRenderer;
+  /** When true the container renders without the `RoundPageContainer` page chrome (e.g. inside a sheet). */
+  embedded?: boolean;
+  /** Rendered inside the composer (bottom-left), before the first message of a new thread. */
+  renderScopePicker?: () => ReactNode;
+  /** Rendered after each thread title in the sidebar. */
+  renderThreadBadge?: (thread: AssistantInterface) => ReactNode;
+  /** When false, the empty state hides the operator-mode toggle and threads use the default engine. Defaults to true. */
+  showOperatorToggle?: boolean;
 }
 
-export function AssistantContainer({ renderApprovalAction }: Props = {}) {
+export function AssistantContainer({
+  renderApprovalAction,
+  renderMention,
+  embedded,
+  renderScopePicker,
+  renderThreadBadge,
+  showOperatorToggle = true,
+}: Props = {}) {
+  const t = useTranslations();
   const ctx = useAssistantContext();
   const showThread = !!ctx.assistant || ctx.sending || ctx.messages.length > 0;
 
-  return (
-    <RoundPageContainer module={Modules.Assistant} fullWidth>
-      <div className="bg-background flex h-full w-full overflow-hidden rounded-lg border">
+  // Memoised: a fresh element on every render fed into RoundPageContainer is
+  // the shape that produces React's "Maximum update depth exceeded".
+  const details = useMemo(
+    () => (
+      // The panel supplies its own padding and border; cancel both so the list
+      // reads as the panel body rather than a card inside it.
+      <div className="-m-4 flex h-full min-h-0 [&>aside]:w-full [&>aside]:border-e-0 [&>aside]:bg-transparent">
         <AssistantSidebar
           threads={ctx.threads}
           activeId={ctx.assistant?.id}
           onSelect={ctx.selectThread}
-          onNew={ctx.startNew}
+          renderThreadBadge={renderThreadBadge}
         />
-        <main className="flex flex-1 flex-col">
-          {!showThread ? (
-            <AssistantEmptyState
-              onSend={ctx.sendMessage}
-              operatorMode={ctx.operatorMode}
-              onOperatorModeChange={ctx.setOperatorMode}
+      </div>
+    ),
+    [ctx.threads, ctx.assistant?.id, ctx.selectThread, renderThreadBadge],
+  );
+
+  const thread = (
+    <>
+      {!showThread ? (
+        <AssistantEmptyState
+          onSend={ctx.sendMessage}
+          operatorMode={ctx.operatorMode}
+          onOperatorModeChange={showOperatorToggle ? ctx.setOperatorMode : undefined}
+          composerLeading={renderScopePicker?.()}
+        />
+      ) : (
+        <>
+          {ctx.assistant ? (
+            <AssistantThreadHeader
+              assistant={ctx.assistant}
+              onRename={(title) => ctx.renameThread(ctx.assistant!.id, title)}
+              onDelete={() => ctx.deleteThread(ctx.assistant!.id)}
             />
           ) : (
-            <>
-              {ctx.assistant ? (
-                <AssistantThreadHeader
-                  assistant={ctx.assistant}
-                  onRename={(title) => ctx.renameThread(ctx.assistant!.id, title)}
-                  onDelete={() => ctx.deleteThread(ctx.assistant!.id)}
-                />
-              ) : (
-                <div className="flex items-center justify-between border-b px-5 py-3" aria-hidden>
-                  <div className="h-5" />
-                </div>
-              )}
-              <AssistantThread
-                messages={ctx.messages}
-                sending={ctx.sending}
-                status={ctx.status}
-                onSelectFollowUp={ctx.sendMessage}
-                failedMessageIds={ctx.failedMessageIds}
-                onRetry={ctx.retrySend}
-                renderApprovalAction={renderApprovalAction}
-              />
-              <AssistantComposer onSend={ctx.sendMessage} disabled={ctx.sending} />
-            </>
+            <div className="flex items-center justify-between border-b px-5 py-3" aria-hidden>
+              <div className="h-5" />
+            </div>
           )}
-        </main>
+          <AssistantThread
+            messages={ctx.messages}
+            sending={ctx.sending}
+            status={ctx.status}
+            onSelectFollowUp={ctx.sendMessage}
+            failedMessageIds={ctx.failedMessageIds}
+            onRetry={ctx.retrySend}
+            renderApprovalAction={renderApprovalAction}
+            renderMention={renderMention ?? EntityMentionLink}
+          />
+          <AssistantComposer onSend={ctx.sendMessage} disabled={ctx.sending} />
+        </>
+      )}
+    </>
+  );
+
+  if (embedded) {
+    return (
+      <div className="bg-background flex h-full w-full overflow-hidden rounded-lg border">
+        <AssistantSidebar
+          threads={ctx.threads}
+          activeId={ctx.assistant?.id}
+          onSelect={ctx.selectThread}
+          onNew={ctx.startNew}
+          renderThreadBadge={renderThreadBadge}
+        />
+        <main className="flex flex-1 flex-col">{thread}</main>
       </div>
+    );
+  }
+
+  // The page mirrors the conversations page: the thread list lives in the
+  // page's details panel, the new-thread action in the page header (set by
+  // AssistantProvider), and the conversation fills the card.
+  return (
+    <RoundPageContainer
+      module={Modules.Assistant}
+      id={ctx.assistant?.id}
+      fullWidth
+      forceHeader
+      defaultDetailsOpen
+      detailsTitle={t("features.assistant.list_title")}
+      detailsIcon={<MessagesSquareIcon />}
+      details={details}
+    >
+      <div className="flex h-full min-h-0 w-full flex-col overflow-hidden">{thread}</div>
     </RoundPageContainer>
   );
 }

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();
+  });
 });