@carlonicora/nextjs-jsonapi 3.12.0 → 3.13.0

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

@@ -0,0 +1,149 @@
+"use client";
+
+import { MessagesSquareIcon, Sparkles } from "lucide-react";
+import { useTranslations } from "next-intl";
+import Link from "next/link";
+import { useCallback, useState } from "react";
+
+import { SectionHeader } from "../../../../components/typography";
+import { Modules } from "../../../../core";
+import { usePageUrlGenerator } from "../../../../hooks";
+import {
+  Button,
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+  Sheet,
+  SheetContent,
+  SheetHeader,
+  SheetTitle,
+  SheetTrigger,
+  Switch,
+} from "../../../../shadcnui";
+import { AssistantComposer } from "../../../assistant/components/parts/AssistantComposer";
+import { AssistantThread } from "../../../assistant/components/parts/AssistantThread";
+import { useHandbookAsk } from "../../hooks/useHandbookAsk";
+
+/**
+ * The ask, reachable from every handbook surface.
+ *
+ * It is the same conversation as `/administration/handbook/chat`, not a second
+ * one: both mount `useHandbookAsk`, so the threads listed here are the threads
+ * listed there and a question asked in the sheet is readable on the route. Only
+ * two things differ.
+ *
+ * 1. No url sync. A sheet floats over the page a reader is on; rewriting the
+ *    address under it would send them somewhere else the moment they close it.
+ *    `syncUrl: false` is exactly that difference.
+ * 2. No thread sidebar. The full list belongs to the route — the sheet carries
+ *    the five most recent threads in a menu and a link to the rest, which is
+ *    what a side panel has room for.
+ *
+ * On the reader the sheet also knows which page is open, and offers to confine
+ * the answer to it. The chip is off by default: a reader asking from inside a
+ * page usually still wants the whole manual to answer, and the narrow search is
+ * the deliberate choice.
+ */
+export function HandbookAskSheet({ handbookPageId }: HandbookAskSheetProps = {}) {
+  const t = useTranslations();
+  const generateUrl = usePageUrlGenerator();
+
+  const { threads, thread, messages, sending, ask, selectThread } = useHandbookAsk({ syncUrl: false });
+  const [scoped, setScoped] = useState(false);
+
+  const chatUrl = `${generateUrl({ page: Modules.HandbookPage })}/chat`;
+  const showThread = !!thread || sending || messages.length > 0;
+
+  const send = useCallback(
+    async (question: string) => {
+      await ask(question, { handbookPageId: scoped ? handbookPageId : undefined });
+    },
+    [ask, handbookPageId, scoped],
+  );
+
+  return (
+    <Sheet>
+      {/* `render`, never a nested <Button>: the trigger draws its own <button>,
+          and wrapping one inside it is invalid HTML. */}
+      <SheetTrigger render={<Button variant="outline" />}>
+        <MessagesSquareIcon className="me-1 h-4 w-4" />
+        {t("handbook.ask.open")}
+      </SheetTrigger>
+      <SheetContent side="end" className="flex w-full flex-col sm:max-w-lg">
+        {/* pe-10 clears SheetContent's own close button, which sits at the
+            inline end of the same row. */}
+        <SheetHeader className="flex-row items-center gap-2 pe-10">
+          <SheetTitle className="flex-1">{t("handbook.chat.title")}</SheetTitle>
+
+          <DropdownMenu>
+            <DropdownMenuTrigger render={<Button variant="ghost" size="sm" />}>
+              {t("handbook.ask.recent")}
+            </DropdownMenuTrigger>
+            <DropdownMenuContent align="end">
+              {threads.slice(0, 5).map((item) => (
+                <DropdownMenuItem key={item.id} onClick={() => void selectThread(item.id)}>
+                  {item.title}
+                </DropdownMenuItem>
+              ))}
+              <DropdownMenuItem>
+                <Link href={chatUrl} className="text-primary w-full font-medium">
+                  {t("handbook.ask.all")}
+                </Link>
+              </DropdownMenuItem>
+            </DropdownMenuContent>
+          </DropdownMenu>
+
+          {thread && (
+            <Link href={`${chatUrl}/${thread.id}`} className="text-primary font-medium">
+              {t("handbook.ask.expand")}
+            </Link>
+          )}
+        </SheetHeader>
+
+        <div className="flex min-h-0 w-full flex-1 flex-col overflow-hidden">
+          {showThread ? (
+            <AssistantThread
+              messages={messages}
+              sending={sending}
+              status={t("handbook.chat.pending")}
+              onSelectFollowUp={send}
+            />
+          ) : (
+            <div className="flex flex-1 items-center justify-center p-6">
+              <div className="flex max-w-sm flex-col items-center text-center">
+                <span className="mb-3 flex h-10 w-10 items-center justify-center rounded-full bg-gradient-to-br from-blue-400 to-violet-500 text-white">
+                  <Sparkles className="h-5 w-5" />
+                </span>
+                <SectionHeader>{t("handbook.chat.empty_state.title")}</SectionHeader>
+                <p className="text-muted-foreground mt-1 text-sm">{t("handbook.chat.empty_state.subtitle")}</p>
+              </div>
+            </div>
+          )}
+
+          {handbookPageId && (
+            <div className="flex items-center gap-2 border-t px-4 pt-3">
+              <Switch checked={scoped} onCheckedChange={setScoped} aria-label={t("handbook.ask.thisPageOnly")} />
+              <span className="text-muted-foreground text-xs">{t("handbook.ask.thisPageOnly")}</span>
+            </div>
+          )}
+
+          <AssistantComposer
+            onSend={send}
+            disabled={sending}
+            placeholder={t("handbook.chat.placeholder")}
+            sendLabel={t("handbook.chat.ask")}
+          />
+        </div>
+      </SheetContent>
+    </Sheet>
+  );
+}
+
+type HandbookAskSheetProps = {
+  /**
+   * The page the reader has open. Present only on the reader; when set, the
+   * sheet offers to confine the next question to that page.
+   */
+  handbookPageId?: string;
+};

package/src/features/handbook/components/containers/HandbookPageContainer.tsx

@@ -0,0 +1,143 @@
+"use client";
+
+import { useTranslations } from "next-intl";
+import { useEffect, useMemo, useState } from "react";
+import { RoundPageContainer } from "../../../../components";
+import { Modules } from "../../../../core";
+import { HandbookProvider } from "../../contexts/HandbookContext";
+import { HandbookPageInterface } from "../../data/HandbookPageInterface";
+import { HandbookPageService } from "../../data/HandbookPageService";
+import { HandbookSectionInterface } from "../../data/HandbookSectionInterface";
+import { HandbookSectionService } from "../../data/HandbookSectionService";
+import { HandbookPageDetails } from "../details/HandbookPageDetails";
+import { HandbookPageNeighbours } from "../details/HandbookPageNeighbours";
+import { HandbookPageToc } from "../details/HandbookPageToc";
+import { HandbookPageNavigator } from "../parts/HandbookPageNavigator";
+import { HandbookAskSheet } from "./HandbookAskSheet";
+
+type HandbookPageContainerProps = {
+  handbookPageId: string;
+};
+
+/** The element the heading index reads its headings out of. */
+const CONTENT_CONTAINER_ID = "handbook-page-content";
+
+/**
+ * Fetches one page client-side from its id.
+ *
+ * The sibling how-to detail uses a server page that dehydrates into a provider.
+ * This one does not, for the same reason the ask surface does not: a handbook
+ * page is read-only and never edited, so there is no shared mutable state for a
+ * provider to hold, and an id string crosses the server/client boundary without
+ * any dehydrate/rehydrate ceremony.
+ *
+ * Three loads, deliberately separate: the page itself, the whole ordered page
+ * list (the navigator and the prev/next pair need it) and the sections. The
+ * section load has its own `try` — a failing sections endpoint degrades the
+ * navigator to raw keys, and must never take the page being read down with it.
+ */
+export default function HandbookPageContainer({ handbookPageId }: HandbookPageContainerProps) {
+  const t = useTranslations();
+  const [handbookPage, setHandbookPage] = useState<HandbookPageInterface | undefined>(undefined);
+  const [pages, setPages] = useState<HandbookPageInterface[]>([]);
+  const [sections, setSections] = useState<HandbookSectionInterface[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    const load = async () => {
+      setIsLoading(true);
+      try {
+        const page = await HandbookPageService.findOne({ id: handbookPageId });
+        if (!cancelled) setHandbookPage(page);
+      } finally {
+        if (!cancelled) setIsLoading(false);
+      }
+    };
+
+    void load();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [handbookPageId]);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    const loadPages = async () => {
+      const allPages = await HandbookPageService.findMany({ fetchAll: true });
+      if (!cancelled) setPages(allPages);
+    };
+
+    const loadSections = async () => {
+      try {
+        const allSections = await HandbookSectionService.findMany();
+        if (!cancelled) setSections(allSections);
+      } catch {
+        if (!cancelled) setSections([]);
+      }
+    };
+
+    void loadPages();
+    void loadSections();
+
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  const section = useMemo(
+    () => sections.find((candidate) => candidate.key === handbookPage?.section),
+    [sections, handbookPage],
+  );
+
+  return (
+    <HandbookProvider
+      page={handbookPage}
+      section={section}
+      functions={handbookPage ? <HandbookAskSheet handbookPageId={handbookPage.id} /> : undefined}
+    >
+      {/*
+        `fullWidth` on the READER, unlike the contents page.
+
+        The container's `max-w-6xl` exists to hold a reading measure, and the
+        two rails are not reading — cramming navigator, prose and heading index
+        into that one column squeezes the prose to a third of it. So the reader
+        takes the full width and caps only its centre column, which is where the
+        measure belongs.
+      */}
+      <RoundPageContainer module={Modules.HandbookPage} fullWidth forceHeader>
+        {isLoading ? null : handbookPage ? (
+          /*
+            `items-start` is what makes `sticky` work on the two side columns:
+            a grid item stretches to the row's height by default, so a sticky
+            child inside it has nowhere to travel and the whole page scrolls
+            instead. With `items-start` each column is only as tall as its
+            content, and the rails hold their place while the page moves.
+
+            Each rail wrapper owns the scrolling — the navigator carries no
+            `max-h` of its own, so there is exactly one scroll container per
+            rail rather than two nested ones.
+          */
+          <div className="grid items-start gap-8 p-4 lg:grid-cols-[240px_minmax(0,1fr)_240px]">
+            <div className="sticky top-4 hidden max-h-[calc(100svh-8rem)] overflow-y-auto lg:block">
+              <HandbookPageNavigator pages={pages} sections={sections} currentId={handbookPage.id} />
+            </div>
+            {/* The measure lives HERE, on the prose, not on the whole page. */}
+            <div id={CONTENT_CONTAINER_ID} className="mx-auto w-full max-w-3xl min-w-0">
+              <HandbookPageDetails handbookPage={handbookPage} />
+              <HandbookPageNeighbours pages={pages} currentId={handbookPage.id} />
+            </div>
+            <div className="sticky top-4 hidden max-h-[calc(100svh-8rem)] overflow-y-auto lg:block">
+              <HandbookPageToc containerId={CONTENT_CONTAINER_ID} />
+            </div>
+          </div>
+        ) : (
+          <span className="text-muted-foreground text-sm">{t("handbook.notFound")}</span>
+        )}
+      </RoundPageContainer>
+    </HandbookProvider>
+  );
+}

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