@carlonicora/nextjs-jsonapi 3.11.0 → 3.13.0

package/src/features/handbook/components/containers/__tests__/HandbookAskContainer.spec.tsx

@@ -0,0 +1,268 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { DataClassRegistry } from "../../../../../core/registry/DataClassRegistry";
+import { ApiRequestDataTypeInterface } from "../../../../../core/interfaces/ApiRequestDataTypeInterface";
+import { ModuleRegistry } from "../../../../../core/registry/ModuleRegistry";
+import { HandbookThread } from "../../../data/HandbookThread";
+import { HandbookThreadMessage } from "../../../data/HandbookThreadMessage";
+import { HandbookThreadMessageService } from "../../../data/HandbookThreadMessageService";
+import { HandbookThreadService } from "../../../data/HandbookThreadService";
+import { HandbookAskContainer } from "../HandbookAskContainer";
+
+vi.mock("../../../data/HandbookThreadService", () => ({
+  HandbookThreadService: {
+    findMany: vi.fn(),
+    findOne: vi.fn(),
+    create: vi.fn(),
+    rename: vi.fn(),
+    delete: vi.fn(),
+  },
+}));
+
+vi.mock("../../../data/HandbookThreadMessageService", () => ({
+  HandbookThreadMessageService: { ask: vi.fn() },
+}));
+
+// RoundPageContainer is page chrome — header, details panel, url rewriting.
+// None of it is under test here, and all of it needs providers this spec has no
+// reason to mount. The stub still renders `details`, because that is where the
+// thread list lives in this layout (copied from AssistantPageContainer).
+vi.mock("../../../../../components/containers/RoundPageContainer", () => ({
+  RoundPageContainer: ({ children, details }: { children?: React.ReactNode; details?: React.ReactNode }) => (
+    <div>
+      {details}
+      {children}
+    </div>
+  ),
+}));
+
+// RoundPageContainer reads Modules.HandbookPage; the handbook models resolve
+// Modules.HandbookThread / Modules.HandbookThreadMessage lazily through
+// ModuleRegistry. Registering is the package's spec convention (see
+// HandbookPage.spec.ts) and is preferred to mocking the core barrel, which the
+// reused assistant components also import from.
+const registerIfAbsent = (key: string, module: ApiRequestDataTypeInterface) => {
+  try {
+    ModuleRegistry.get(key as any);
+  } catch {
+    ModuleRegistry.register(key, module);
+  }
+};
+
+beforeAll(() => {
+  registerIfAbsent("HandbookPage", { name: "handbookpages" } as any);
+  const threadModule = { name: "handbookthreads", model: HandbookThread } as any;
+  const messageModule = { name: "handbookthreadmessages", model: HandbookThreadMessage } as any;
+  registerIfAbsent("HandbookThread", threadModule);
+  registerIfAbsent("HandbookThreadMessage", messageModule);
+  // `_readIncluded` and `rehydrate()` resolve the CONSTRUCTOR through
+  // DataClassRegistry, which the app's Bootstrapper fills from the same module
+  // definitions — registering only in ModuleRegistry leaves side-loaded
+  // messages unrehydratable.
+  DataClassRegistry.registerObjectClass(threadModule, HandbookThread as any);
+  DataClassRegistry.registerObjectClass(messageModule, HandbookThreadMessage as any);
+});
+
+function buildThread(params: {
+  id: string;
+  title: string;
+  updatedAt?: string;
+  messages?: { id: string; role: "user" | "assistant"; content: string; position: number; sources?: string[] }[];
+}): HandbookThread {
+  const messages = params.messages ?? [];
+  return new HandbookThread().rehydrate({
+    jsonApi: {
+      id: params.id,
+      type: "handbookthreads",
+      attributes: { title: params.title },
+      meta: { updatedAt: params.updatedAt ?? new Date().toISOString() },
+      relationships: {
+        messages: { data: messages.map((m) => ({ id: m.id, type: "handbookthreadmessages" })) },
+      },
+    },
+    included: messages.map((m) => ({
+      id: m.id,
+      type: "handbookthreadmessages",
+      attributes: { role: m.role, content: m.content, position: m.position, sources: m.sources ?? [] },
+    })),
+  } as any);
+}
+
+/** The send control belongs to the shared AssistantComposer, not to this feature. */
+const sendButton = () => screen.getByRole("button", { name: /handbook\.chat\.ask/i });
+
+describe("HandbookAskContainer", () => {
+  beforeEach(() => {
+    vi.mocked(HandbookThreadService.findMany).mockReset().mockResolvedValue([]);
+    vi.mocked(HandbookThreadService.findOne).mockReset();
+    vi.mocked(HandbookThreadService.create).mockReset();
+    vi.mocked(HandbookThreadService.delete).mockReset().mockResolvedValue(undefined);
+    vi.mocked(HandbookThreadService.rename).mockReset().mockResolvedValue(undefined);
+    vi.mocked(HandbookThreadMessageService.ask).mockReset().mockResolvedValue(undefined);
+  });
+
+  it("reuses the shared composer and sidebar but never the assistant's copy", async () => {
+    render(<HandbookAskContainer />);
+
+    expect(screen.getByPlaceholderText("handbook.chat.placeholder")).toBeInTheDocument();
+    expect(screen.queryByPlaceholderText("features.assistant.composer_placeholder")).not.toBeInTheDocument();
+    expect(sendButton()).toBeDisabled();
+    expect(screen.getByRole("button", { name: /handbook\.chat\.new/ })).toBeInTheDocument();
+    await waitFor(() => expect(screen.getByText("handbook.chat.empty_sidebar")).toBeInTheDocument());
+    expect(screen.queryByText("features.assistant.empty_sidebar")).not.toBeInTheDocument();
+  });
+
+  it("shows the handbook empty state until a thread exists", async () => {
+    render(<HandbookAskContainer />);
+
+    expect(screen.getByText("handbook.chat.empty_state.title")).toBeInTheDocument();
+    expect(screen.getByText("handbook.chat.empty_state.subtitle")).toBeInTheDocument();
+    await waitFor(() => expect(HandbookThreadService.findMany).toHaveBeenCalled());
+  });
+
+  it("lists the previous threads in the sidebar", async () => {
+    vi.mocked(HandbookThreadService.findMany).mockResolvedValue([
+      buildThread({ id: "t1", title: "Filtri di azienda" }),
+      buildThread({ id: "t2", title: "Porte del worker" }),
+    ]);
+
+    render(<HandbookAskContainer />);
+
+    await waitFor(() => expect(screen.getByRole("button", { name: "Filtri di azienda" })).toBeInTheDocument());
+    expect(screen.getByRole("button", { name: "Porte del worker" })).toBeInTheDocument();
+  });
+
+  it("loads the messages of the thread picked from the sidebar", async () => {
+    vi.mocked(HandbookThreadService.findMany).mockResolvedValue([
+      buildThread({ id: "t1", title: "Filtri di azienda" }),
+    ]);
+    vi.mocked(HandbookThreadService.findOne).mockResolvedValue(
+      buildThread({
+        id: "t1",
+        title: "Filtri di azienda",
+        messages: [
+          { id: "m1", role: "user", content: "Come funziona buildDefaultMatch?", position: 0 },
+          { id: "m2", role: "assistant", content: "Inietta il filtro di azienda.", position: 1 },
+        ],
+      }),
+    );
+
+    render(<HandbookAskContainer />);
+    await userEvent.click(await screen.findByRole("button", { name: "Filtri di azienda" }));
+
+    await waitFor(() => expect(HandbookThreadService.findOne).toHaveBeenCalledWith({ id: "t1" }));
+    expect(await screen.findByText("Come funziona buildDefaultMatch?")).toBeInTheDocument();
+    expect(screen.getByText(/Inietta il filtro di azienda/)).toBeInTheDocument();
+  });
+
+  it("asks the trimmed question, creates a thread and shows its title", async () => {
+    vi.mocked(HandbookThreadService.create).mockResolvedValue(buildThread({ id: "t9", title: "Filtri di azienda" }));
+    vi.mocked(HandbookThreadService.findOne).mockResolvedValue(
+      buildThread({
+        id: "t9",
+        title: "Filtri di azienda",
+        messages: [
+          { id: "m1", role: "user", content: "Come funziona buildDefaultMatch?", position: 0 },
+          { id: "m2", role: "assistant", content: "Inietta il filtro di azienda.", position: 1 },
+        ],
+      }),
+    );
+
+    render(<HandbookAskContainer />);
+    await userEvent.type(screen.getByRole("textbox"), "  Come funziona buildDefaultMatch?  ");
+    await userEvent.click(sendButton());
+
+    await waitFor(() =>
+      expect(HandbookThreadService.create).toHaveBeenCalledWith(
+        expect.objectContaining({ question: "Come funziona buildDefaultMatch?" }),
+      ),
+    );
+
+    // The title only exists server-side until the thread is read back, so its
+    // appearance in the sidebar row is the proof the transcript was reloaded.
+    await waitFor(() => expect(screen.getAllByText("Filtri di azienda").length).toBeGreaterThan(0));
+    expect(screen.getByText(/Inietta il filtro di azienda/)).toBeInTheDocument();
+
+    // There is exactly ONE header on this page — RoundPageContainer's. The
+    // assistant's per-thread header is deliberately not rendered, so neither
+    // its rename nor its delete control may appear.
+    expect(screen.queryByRole("button", { name: "features.assistant.rename" })).toBeNull();
+    expect(screen.queryByRole("button", { name: "features.assistant.delete" })).toBeNull();
+  });
+
+  it("appends to the open thread instead of creating a second one", async () => {
+    vi.mocked(HandbookThreadService.findMany).mockResolvedValue([
+      buildThread({ id: "t1", title: "Filtri di azienda" }),
+    ]);
+    vi.mocked(HandbookThreadService.findOne).mockResolvedValue(
+      buildThread({
+        id: "t1",
+        title: "Filtri di azienda",
+        messages: [{ id: "m1", role: "assistant", content: "Inietta il filtro di azienda.", position: 1 }],
+      }),
+    );
+
+    render(<HandbookAskContainer />);
+    await userEvent.click(await screen.findByRole("button", { name: "Filtri di azienda" }));
+    await waitFor(() => expect(screen.getByText(/Inietta il filtro di azienda/)).toBeInTheDocument());
+
+    await userEvent.type(screen.getByRole("textbox"), "E i cursori?");
+    await userEvent.click(sendButton());
+
+    await waitFor(() =>
+      expect(HandbookThreadMessageService.ask).toHaveBeenCalledWith(
+        expect.objectContaining({ threadId: "t1", question: "E i cursori?" }),
+      ),
+    );
+    expect(HandbookThreadService.create).not.toHaveBeenCalled();
+  });
+
+  it("renders the cited sources inside the answer", async () => {
+    vi.mocked(HandbookThreadService.create).mockResolvedValue(buildThread({ id: "t9", title: "Fonti" }));
+    vi.mocked(HandbookThreadService.findOne).mockResolvedValue(
+      buildThread({
+        id: "t9",
+        title: "Fonti",
+        messages: [
+          {
+            id: "m2",
+            role: "assistant",
+            content: "Inietta il filtro di azienda.",
+            position: 1,
+            sources: ["03-backend/repositories.md", "02-framework/security.md"],
+          },
+        ],
+      }),
+    );
+
+    render(<HandbookAskContainer />);
+    await userEvent.type(screen.getByRole("textbox"), "Perché?");
+    await userEvent.click(sendButton());
+
+    await waitFor(() => expect(screen.getByText("03-backend/repositories.md")).toBeInTheDocument());
+    expect(screen.getByText("02-framework/security.md")).toBeInTheDocument();
+    expect(screen.getByText("handbook.chat.sources")).toBeInTheDocument();
+  });
+
+  it("surfaces a failure as an assistant message rather than an error pane", async () => {
+    vi.mocked(HandbookThreadService.create).mockRejectedValue(new Error("AI is not configured"));
+
+    render(<HandbookAskContainer />);
+    await userEvent.type(screen.getByRole("textbox"), "Perché?");
+    await userEvent.click(sendButton());
+
+    await waitFor(() => expect(screen.getByText("handbook.chat.failed")).toBeInTheDocument());
+  });
+
+  it("keeps the asked question in the transcript when the answer fails", async () => {
+    vi.mocked(HandbookThreadService.create).mockRejectedValue(new Error("boom"));
+
+    render(<HandbookAskContainer />);
+    await userEvent.type(screen.getByRole("textbox"), "Che porte usa il worker?");
+    await userEvent.click(sendButton());
+
+    await waitFor(() => expect(screen.getByText("Che porte usa il worker?")).toBeInTheDocument());
+  });
+});

package/src/features/handbook/components/containers/__tests__/HandbookAskSheet.spec.tsx

@@ -0,0 +1,143 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { ApiRequestDataTypeInterface } from "../../../../../core/interfaces/ApiRequestDataTypeInterface";
+import { ModuleRegistry } from "../../../../../core/registry/ModuleRegistry";
+import { HandbookAskSheet } from "../HandbookAskSheet";
+
+/**
+ * The conversation itself is `useHandbookAsk`'s, and its own spec covers it.
+ * What this file proves is the sheet: what it opens with, what the recent menu
+ * holds, and what the page chip does to the next question. So the hook is
+ * mocked — but with real React state behind `ask`, because "the expand link
+ * appears once a thread exists" is a transition, not a snapshot.
+ */
+const fixtures = vi.hoisted(() => ({
+  ask: vi.fn(),
+  selectThread: vi.fn(),
+  startNew: vi.fn(),
+  threads: [] as { id: string; title: string }[],
+}));
+
+vi.mock("../../../hooks/useHandbookAsk", async () => {
+  const { useState } = await import("react");
+  return {
+    useHandbookAsk: () => {
+      const [thread, setThread] = useState<{ id: string; title: string } | undefined>(undefined);
+      return {
+        threads: fixtures.threads,
+        thread,
+        messages: [],
+        sending: false,
+        ask: async (question: string, options?: { handbookPageId?: string }) => {
+          fixtures.ask(question, options);
+          setThread({ id: "t1", title: "Filtri di azienda" });
+        },
+        selectThread: fixtures.selectThread,
+        startNew: fixtures.startNew,
+      };
+    },
+  };
+});
+
+// The sheet builds its links with `usePageUrlGenerator`, which reads
+// `Modules.HandbookPage.pageUrl` through the registry.
+const registerIfAbsent = (key: string, module: ApiRequestDataTypeInterface) => {
+  try {
+    ModuleRegistry.get(key as any);
+  } catch {
+    ModuleRegistry.register(key, module);
+  }
+};
+
+beforeAll(() => {
+  registerIfAbsent("HandbookPage", { name: "handbookpages", pageUrl: "/administration/handbook" } as any);
+});
+
+const open = async () => {
+  await userEvent.click(screen.getByRole("button", { name: /handbook\.ask\.open/ }));
+};
+
+describe("HandbookAskSheet", () => {
+  beforeEach(() => {
+    fixtures.ask.mockReset();
+    fixtures.selectThread.mockReset();
+    fixtures.startNew.mockReset();
+    fixtures.threads = [];
+  });
+
+  it("opens on a new thread", async () => {
+    render(<HandbookAskSheet handbookPageId="p2" />);
+
+    await open();
+
+    expect(await screen.findByText("handbook.chat.empty_state.title")).toBeInTheDocument();
+    expect(screen.getByPlaceholderText("handbook.chat.placeholder")).toBeInTheDocument();
+  });
+
+  it("lists the five most recent threads and links to the full route", async () => {
+    fixtures.threads = Array.from({ length: 7 }, (_, index) => ({
+      id: `t${index}`,
+      title: `Conversazione ${index}`,
+    }));
+
+    render(<HandbookAskSheet />);
+    await open();
+    await userEvent.click(await screen.findByRole("button", { name: "handbook.ask.recent" }));
+
+    // Five threads plus the "all conversations" row.
+    expect(await screen.findAllByRole("menuitem")).toHaveLength(6);
+    expect(screen.getByText("Conversazione 4")).toBeInTheDocument();
+    expect(screen.queryByText("Conversazione 5")).not.toBeInTheDocument();
+    expect(screen.getByRole("link", { name: "handbook.ask.all" })).toHaveAttribute(
+      "href",
+      "/administration/handbook/chat",
+    );
+  });
+
+  it("opens a thread picked from the recent menu", async () => {
+    fixtures.threads = [{ id: "t3", title: "Filtri di azienda" }];
+
+    render(<HandbookAskSheet />);
+    await open();
+    await userEvent.click(await screen.findByRole("button", { name: "handbook.ask.recent" }));
+    await userEvent.click(await screen.findByRole("menuitem", { name: "Filtri di azienda" }));
+
+    expect(fixtures.selectThread).toHaveBeenCalledWith("t3");
+  });
+
+  it("scopes the question to the page only when the chip is on", async () => {
+    render(<HandbookAskSheet handbookPageId="p2" />);
+    await open();
+
+    await userEvent.type(await screen.findByRole("textbox"), "Why?{Enter}");
+    expect(fixtures.ask).toHaveBeenLastCalledWith("Why?", { handbookPageId: undefined });
+
+    await userEvent.click(screen.getByRole("switch", { name: "handbook.ask.thisPageOnly" }));
+    await userEvent.type(screen.getByRole("textbox"), "Again?{Enter}");
+    expect(fixtures.ask).toHaveBeenLastCalledWith("Again?", { handbookPageId: "p2" });
+  });
+
+  it("offers no page chip when no page is open", async () => {
+    render(<HandbookAskSheet />);
+    await open();
+
+    await screen.findByRole("textbox");
+    expect(screen.queryByRole("switch", { name: "handbook.ask.thisPageOnly" })).toBeNull();
+  });
+
+  it("expands to the route on the open thread", async () => {
+    render(<HandbookAskSheet />);
+    await open();
+
+    expect(screen.queryByRole("link", { name: "handbook.ask.expand" })).toBeNull();
+
+    await userEvent.type(await screen.findByRole("textbox"), "Why?{Enter}");
+
+    expect(await screen.findByRole("link", { name: "handbook.ask.expand" })).toHaveAttribute(
+      "href",
+      "/administration/handbook/chat/t1",
+    );
+  });
+});