@carlonicora/nextjs-jsonapi 3.11.0 → 3.13.0

package/src/features/handbook/hooks/useHandbookAsk.ts

@@ -0,0 +1,213 @@
+"use client";
+
+import { useTranslations } from "next-intl";
+import { useCallback, useEffect, useState } from "react";
+import { v4 } from "uuid";
+
+import { Modules, rehydrate } from "../../../core";
+import { usePageUrlGenerator } from "../../../hooks";
+import { HandbookThreadMessage } from "../data/HandbookThreadMessage";
+import type { HandbookThreadInterface } from "../data/HandbookThreadInterface";
+import type { HandbookThreadMessageInterface } from "../data/HandbookThreadMessageInterface";
+import { HandbookThreadMessageService } from "../data/HandbookThreadMessageService";
+import { HandbookThreadService } from "../data/HandbookThreadService";
+
+/**
+ * The state of one handbook conversation, extracted verbatim from
+ * `HandbookAskContainer`.
+ *
+ * Two surfaces now hold a conversation — the full `/chat` route and the side
+ * sheet reachable from contents and reader — and they must behave identically:
+ * same optimistic user message, same read-back through
+ * `HandbookThreadService.findOne`, same error branch. Duplicating that in two
+ * components is how the two drift, so it lives here and both consume it.
+ *
+ * The one difference is the address bar. The route keeps the url on the open
+ * thread; opening a sheet is not a navigation, so the sheet passes
+ * `syncUrl: false` and nothing is written to history.
+ */
+
+/**
+ * Sources ride in the markdown rather than in a bespoke block: the message
+ * renderer already renders markdown, and a list of file paths is exactly that.
+ *
+ * The message is rebuilt through `dehydrate()` + `rehydrate()` rather than a
+ * fresh `buildLocal`, so it keeps its id and React does not remount the bubble
+ * on every render. Mirrors `withPatchedTitle` in `AssistantContext`.
+ */
+function withSources(messages: HandbookThreadMessageInterface[], label: string): HandbookThreadMessageInterface[] {
+  return messages.map((message) => withSourcesInContent(message, label));
+}
+
+function withSourcesInContent(message: HandbookThreadMessageInterface, label: string): HandbookThreadMessageInterface {
+  if (message.role !== "assistant" || message.sources.length === 0) return message;
+
+  const dehydrated = message.dehydrate();
+  const content = `${message.content}\n\n**${label}**\n\n${message.sources.map((source) => `- \`${source}\``).join("\n")}`;
+
+  return rehydrate<HandbookThreadMessageInterface>(Modules.HandbookThreadMessage, {
+    jsonApi: {
+      ...dehydrated.jsonApi,
+      attributes: { ...(dehydrated.jsonApi?.attributes ?? {}), content },
+    },
+    included: dehydrated.included,
+  });
+}
+
+export type UseHandbookAskParams = {
+  /**
+   * Keep the address bar on the open thread. Defaults to `true`, the route's
+   * behaviour; the sheet passes `false`.
+   */
+  syncUrl?: boolean;
+  /** Thread to open on mount, when the route carries one. */
+  handbookThreadId?: string;
+};
+
+export type UseHandbookAskResult = {
+  threads: HandbookThreadInterface[];
+  thread: HandbookThreadInterface | undefined;
+  messages: HandbookThreadMessageInterface[];
+  sending: boolean;
+  ask: (question: string, options?: { handbookPageId?: string }) => Promise<void>;
+  selectThread: (id: string) => Promise<void>;
+  startNew: () => void;
+};
+
+export function useHandbookAsk(params?: UseHandbookAskParams): UseHandbookAskResult {
+  const t = useTranslations();
+  const generateUrl = usePageUrlGenerator();
+
+  const shouldSyncUrl = params?.syncUrl ?? true;
+  const handbookThreadId = params?.handbookThreadId;
+
+  const [threads, setThreads] = useState<HandbookThreadInterface[]>([]);
+  const [thread, setThread] = useState<HandbookThreadInterface | undefined>(undefined);
+  const [messages, setMessages] = useState<HandbookThreadMessageInterface[]>([]);
+  const [sending, setSending] = useState(false);
+
+  const sourcesLabel = t("handbook.chat.sources");
+
+  useEffect(() => {
+    let cancelled = false;
+    (async () => {
+      const loaded = await HandbookThreadService.findMany();
+      if (!cancelled) setThreads(loaded);
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  // A routed thread id opens that thread on mount, so the url survives a reload
+  // or a pasted link. Runs once per id; selecting from the list takes the other
+  // path and only replaces the url.
+  useEffect(() => {
+    if (!handbookThreadId) return;
+    let cancelled = false;
+    (async () => {
+      const selected = await HandbookThreadService.findOne({ id: handbookThreadId });
+      if (cancelled) return;
+      setThread(selected);
+      setMessages(withSources(selected.messages, sourcesLabel));
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [handbookThreadId]);
+
+  /**
+   * Keep the address bar on the open thread, the way ConversationListItem does
+   * (`window.history.replaceState` with the generated url) — selecting a thread
+   * is not a navigation, so this replaces rather than pushes.
+   *
+   * A no-op when the caller asked for no url sync: the sheet floats over a page
+   * that is itself the navigation, and rewriting the url under it would send a
+   * reader who closes the sheet somewhere they never went.
+   */
+  const syncUrl = useCallback(
+    (id?: string) => {
+      if (!shouldSyncUrl) return;
+      const base = `${generateUrl({ page: Modules.HandbookPage })}/chat`;
+      window.history.replaceState(null, "", id ? `${base}/${id}` : base);
+    },
+    [generateUrl, shouldSyncUrl],
+  );
+
+  const selectThread = useCallback(
+    async (id: string) => {
+      const selected = await HandbookThreadService.findOne({ id });
+      setThread(selected);
+      setMessages(withSources(selected.messages, sourcesLabel));
+      syncUrl(id);
+    },
+    [syncUrl],
+  );
+
+  const startNew = useCallback(() => {
+    setThread(undefined);
+    setMessages([]);
+    syncUrl(undefined);
+  }, [syncUrl]);
+
+  const ask = useCallback(
+    async (question: string, options?: { handbookPageId?: string }) => {
+      const trimmed = question.trim();
+      if (!trimmed || sending) return;
+
+      const position = messages.length;
+      setMessages((current) => [
+        ...current,
+        HandbookThreadMessage.buildLocal({ role: "user", content: trimmed, position, isOptimistic: true }),
+      ]);
+      setSending(true);
+
+      try {
+        // Both branches end in the same read: only the single-thread endpoint
+        // side-loads the messages, so the transcript always comes from there.
+        let id = thread?.id;
+        if (id === undefined) {
+          const created = await HandbookThreadService.create({
+            id: v4(),
+            question: trimmed,
+            handbookPageId: options?.handbookPageId,
+          });
+          id = created.id;
+          setThreads((current) => [created, ...current]);
+        } else {
+          await HandbookThreadMessageService.ask({
+            id: v4(),
+            threadId: id,
+            question: trimmed,
+            handbookPageId: options?.handbookPageId,
+          });
+        }
+
+        const loaded = await HandbookThreadService.findOne({ id });
+        setThread(loaded);
+        setMessages(withSources(loaded.messages, sourcesLabel));
+        // The server derives the title from the first question, so the list row
+        // created a moment ago has to pick it up.
+        setThreads((current) => current.map((item) => (item.id === loaded.id ? loaded : item)));
+        syncUrl(loaded.id);
+      } catch {
+        // 400 when the installation has no usable AI configuration, 403 for a
+        // non-administrator. Neither is actionable from here, so both surface
+        // as one assistant-side message rather than a bespoke error pane.
+        setMessages((current) => [
+          ...current,
+          HandbookThreadMessage.buildLocal({
+            role: "assistant",
+            content: t("handbook.chat.failed"),
+            position: position + 1,
+          }),
+        ]);
+      } finally {
+        setSending(false);
+      }
+    },
+    [messages.length, sending, syncUrl, t, thread?.id],
+  );
+
+  return { threads, thread, messages, sending, ask, selectThread, startNew };
+}

package/src/features/handbook/i18n-keys.ts

@@ -0,0 +1,46 @@
+/**
+ * The fixed namespace of i18n keys the handbook feature reads via
+ * useTranslations. Consuming apps must define each entry in their
+ * messages/<locale>.json — this list is the contract between the package and
+ * the app, and the names are frozen: an app that wants different wording
+ * changes its own translation, never the key.
+ *
+ * Mirrors the contract shipped by the administration feature
+ * (features/administration/i18n-keys.ts).
+ */
+export const handbookI18nKeys = [
+  "handbook.title",
+  "handbook.subtitle",
+  "handbook.sync",
+  "handbook.syncing",
+  "handbook.synced",
+  "handbook.syncFailed",
+  "handbook.empty",
+  "handbook.notConfigured",
+  "handbook.chat.title",
+  "handbook.chat.placeholder",
+  "handbook.chat.ask",
+  "handbook.chat.pending",
+  "handbook.chat.failed",
+  "handbook.chat.sources",
+  "handbook.chat.list_title",
+  "handbook.chat.new",
+  "handbook.chat.empty_sidebar",
+  "handbook.chat.rename_placeholder",
+  "handbook.chat.delete_confirm",
+  "handbook.chat.empty_state.title",
+  "handbook.chat.empty_state.subtitle",
+  "handbook.contents.title",
+  "handbook.contents.status",
+  "handbook.contents.failures",
+  "handbook.reader.contents",
+  "handbook.reader.onThisPage",
+  "handbook.reader.previous",
+  "handbook.reader.next",
+  "handbook.ask.open",
+  "handbook.ask.recent",
+  "handbook.ask.all",
+  "handbook.ask.expand",
+  "handbook.ask.thisPageOnly",
+  "handbook.sections.untitled",
+] as const;

package/src/features/handbook/index.ts

@@ -0,0 +1,7 @@
+export * from "./HandbookPageModule";
+export * from "./HandbookSectionModule";
+export * from "./HandbookThreadMessageModule";
+export * from "./HandbookThreadModule";
+export * from "./components";
+export * from "./contexts/HandbookContext";
+export * from "./data";

package/src/features/how-to/components/forms/HowToEditor.tsx

@@ -239,7 +239,6 @@ function HowToEditorInternal({
         const payload: HowToInput = {
           id: values.id,
           name: values.name,
-          authorId: "",
           description: values.description,
           pages: HowTo.serializePagesToString(values.pages),
           howToType: values.howToType,

package/src/features/how-to/components/forms/HowToReindexButton.spec.tsx

@@ -0,0 +1,84 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { showError, showToast } from "../../../../utils/toast";
+import { HowToService } from "../../data/HowToService";
+import HowToReindexButton from "./HowToReindexButton";
+
+vi.mock("../../data/HowToService", () => ({
+  HowToService: { reindex: vi.fn() },
+}));
+
+vi.mock("../../../../utils/toast", () => ({
+  showToast: vi.fn(),
+  showError: vi.fn(),
+}));
+
+vi.mock("next-intl", () => ({
+  useTranslations: () => (key: string) => key,
+}));
+
+describe("HowToReindexButton", () => {
+  beforeEach(() => {
+    vi.mocked(HowToService.reindex).mockReset().mockResolvedValue(undefined);
+    vi.mocked(showToast).mockReset();
+    vi.mocked(showError).mockReset();
+  });
+
+  it("renders the action label", () => {
+    render(<HowToReindexButton refresh={vi.fn().mockResolvedValue(undefined)} />);
+
+    expect(screen.getByRole("button")).toHaveTextContent("howto.reindex.action");
+  });
+
+  it("reindexes, then refreshes the list", async () => {
+    const refresh = vi.fn().mockResolvedValue(undefined);
+    render(<HowToReindexButton refresh={refresh} />);
+
+    await userEvent.click(screen.getByRole("button"));
+
+    await waitFor(() => expect(HowToService.reindex).toHaveBeenCalledTimes(1));
+    await waitFor(() => expect(refresh).toHaveBeenCalledTimes(1));
+  });
+
+  it("shows the running state while the reindex is in flight", async () => {
+    let resolveReindex: () => void = () => {};
+    vi.mocked(HowToService.reindex).mockReturnValue(
+      new Promise<void>((resolve) => {
+        resolveReindex = resolve;
+      }),
+    );
+    render(<HowToReindexButton refresh={vi.fn().mockResolvedValue(undefined)} />);
+
+    await userEvent.click(screen.getByRole("button"));
+
+    await waitFor(() => expect(screen.getByRole("button")).toHaveTextContent("howto.reindex.running"));
+    expect(screen.getByRole("button")).toBeDisabled();
+
+    resolveReindex();
+    await waitFor(() => expect(screen.getByRole("button")).toHaveTextContent("howto.reindex.action"));
+  });
+
+  it("shows the done state once the reindex succeeds", async () => {
+    render(<HowToReindexButton refresh={vi.fn().mockResolvedValue(undefined)} />);
+
+    await userEvent.click(screen.getByRole("button"));
+
+    await waitFor(() => expect(showToast).toHaveBeenCalledWith("howto.reindex.done"));
+    expect(showError).not.toHaveBeenCalled();
+  });
+
+  it("shows the failed state when the reindex rejects, and re-enables itself", async () => {
+    vi.mocked(HowToService.reindex).mockRejectedValue(new Error("boom"));
+    const refresh = vi.fn().mockResolvedValue(undefined);
+    render(<HowToReindexButton refresh={refresh} />);
+
+    await userEvent.click(screen.getByRole("button"));
+
+    await waitFor(() => expect(showError).toHaveBeenCalledWith("howto.reindex.failed"));
+    expect(showToast).not.toHaveBeenCalled();
+    expect(refresh).not.toHaveBeenCalled();
+    await waitFor(() => expect(screen.getByRole("button")).not.toBeDisabled());
+  });
+});

package/src/features/how-to/components/forms/HowToReindexButton.tsx

@@ -0,0 +1,46 @@
+"use client";
+
+import { useTranslations } from "next-intl";
+import { useState } from "react";
+
+import { Button } from "../../../../shadcnui";
+import { showError, showToast } from "../../../../utils/toast";
+import { HowToService } from "../../data/HowToService";
+
+type HowToReindexButtonProps = {
+  refresh: () => Promise<void>;
+};
+
+/**
+ * Re-queues every guide for chunking.
+ *
+ * Guides are chunked on create and update only, so one written before chunking
+ * existed — or one whose chunks were dropped — is invisible to the help chat
+ * with no way back in. This is the way back in.
+ *
+ * The control is a plain Button, not a trigger: it opens nothing, so the
+ * render-prop composition rule for Base UI triggers does not apply here.
+ */
+export default function HowToReindexButton({ refresh }: HowToReindexButtonProps) {
+  const t = useTranslations();
+  const [isReindexing, setIsReindexing] = useState(false);
+
+  const onReindex = async () => {
+    setIsReindexing(true);
+    try {
+      await HowToService.reindex();
+      await refresh();
+      showToast(t(`howto.reindex.done`));
+    } catch {
+      showError(t(`howto.reindex.failed`));
+    } finally {
+      setIsReindexing(false);
+    }
+  };
+
+  return (
+    <Button variant="outline" onClick={onReindex} disabled={isReindexing}>
+      {isReindexing ? t(`howto.reindex.running`) : t(`howto.reindex.action`)}
+    </Button>
+  );
+}

package/src/features/how-to/components/index.ts

@@ -7,5 +7,6 @@ export { default as HowToDetails } from "./details/HowToDetails";
 export { default as HowToDeleter } from "./forms/HowToDeleter";
 export { default as HowToEditor } from "./forms/HowToEditor";
 export { default as HowToMultiSelector } from "./forms/HowToMultiSelector";
+export { default as HowToReindexButton } from "./forms/HowToReindexButton";
 export { default as HowToSelector } from "./forms/HowToSelector";
 export { default as HowToList } from "./lists/HowToList";

package/src/features/how-to/components/lists/HowToList.tsx

@@ -10,6 +10,7 @@ import { HowToInterface } from "../../data/HowToInterface";
 import { HowToService } from "../../data/HowToService";
 import "../../hooks/useHowToTableStructure";
 import HowToEditor from "../forms/HowToEditor";
+import HowToReindexButton from "../forms/HowToReindexButton";
 
 type HowToListProps = {
   fullWidth?: boolean;
@@ -24,7 +25,10 @@ export default function HowToList({ fullWidth }: HowToListProps) {
     retrieverParams: {},
   });
 
-  const functions: ReactNode[] = [<HowToEditor key="create-how-to" />];
+  const functions: ReactNode[] = [
+    <HowToReindexButton key="reindex-how-tos" refresh={data.refresh} />,
+    <HowToEditor key="create-how-to" />,
+  ];
 
   return (
     <ContentListTable

package/src/features/how-to/data/HowTo.spec.ts

@@ -11,16 +11,34 @@ const howToModule: ApiRequestDataTypeInterface = {
   model: HowTo,
 } as any;
 
+const userModule: ApiRequestDataTypeInterface = {
+  name: "users",
+  model: HowTo,
+} as any;
+
 beforeAll(() => {
   ModuleRegistry.register("HowTo", howToModule);
+  ModuleRegistry.register("User", userModule);
 });
 
+/** Collect every `id` value at any depth of a serialised payload. */
+function collectIds(value: any, ids: string[] = []): string[] {
+  if (Array.isArray(value)) {
+    for (const item of value) collectIds(item, ids);
+  } else if (value && typeof value === "object") {
+    for (const [key, child] of Object.entries(value)) {
+      if (key === "id") ids.push(child as string);
+      else collectIds(child, ids);
+    }
+  }
+  return ids;
+}
+
 describe("HowTo.createJsonApi", () => {
   it("serialises the new attributes", () => {
     const res = new HowTo().createJsonApi({
       id: "11111111-1111-4111-8111-111111111111",
       name: "Add an NPC",
-      authorId: "",
       description: [{ type: "paragraph", content: [] }],
       howToType: "how-to",
       slug: "add-an-npc",
@@ -40,4 +58,46 @@ describe("HowTo.createJsonApi", () => {
     expect(a.draft).toBe(false);
     expect(typeof a.description).toBe("string"); // existing: BlockNote JSON stringified
   });
+
+  it("emits no author relationship when the how-to has no author", () => {
+    // The backend HowTo descriptor declares `relationships: {}` — a how-to has no
+    // author on the wire, so the editor must not invent one.
+    const res = new HowTo().createJsonApi({
+      id: "11111111-1111-4111-8111-111111111111",
+      name: "Add an NPC",
+      description: [{ type: "paragraph", content: [] }],
+    });
+
+    expect(res.data.relationships).toEqual({});
+    expect(res.data.relationships.author).toBeUndefined();
+    expect("author" in res.data.relationships).toBe(false);
+  });
+
+  it("emits no empty-string id anywhere in the payload", () => {
+    const res = new HowTo().createJsonApi({
+      id: "11111111-1111-4111-8111-111111111111",
+      name: "Add an NPC",
+      description: [{ type: "paragraph", content: [] }],
+    });
+
+    const ids = collectIds(res);
+    expect(ids).toEqual(["11111111-1111-4111-8111-111111111111"]);
+    expect(ids).not.toContain("");
+    expect(JSON.stringify(res)).not.toContain('"id":""');
+  });
+
+  it("still emits the author relationship when a real author id is supplied", () => {
+    // Guards the ContentInput widening: content types that DO carry an author
+    // keep serialising it through Content.addContentInput.
+    const res = new HowTo().createJsonApi({
+      id: "11111111-1111-4111-8111-111111111111",
+      name: "Add an NPC",
+      authorId: "22222222-2222-4222-8222-222222222222",
+      description: [{ type: "paragraph", content: [] }],
+    });
+
+    expect(res.data.relationships.author).toEqual({
+      data: { type: "users", id: "22222222-2222-4222-8222-222222222222" },
+    });
+  });
 });

package/src/features/how-to/data/HowToService.ts

@@ -59,6 +59,19 @@ export class HowToService extends AbstractService {
     });
   }
 
+  /**
+   * POST /howtos/reindex — re-queues every guide for chunking. Replies 204.
+   * Chunking otherwise only happens on create and update, so a guide that was
+   * never chunked stays invisible to help-mode retrieval with no way back.
+   */
+  static async reindex(): Promise<void> {
+    await this.callApi({
+      type: Modules.HowTo,
+      method: HttpMethod.POST,
+      endpoint: new EndpointCreator({ endpoint: Modules.HowTo, id: "reindex" }).generate(),
+    });
+  }
+
   static async findPublished(params: { howToType?: string } = {}): Promise<HowToInterface[]> {
     const endpoint = new EndpointCreator({ endpoint: `public/${Modules.HowTo.name}` });
     if (params.howToType) endpoint.addAdditionalParam("type", params.howToType);