@carlonicora/nextjs-jsonapi 3.11.0 → 3.13.0

package/src/features/handbook/HandbookThreadModule.ts

@@ -0,0 +1,29 @@
+import { MessagesSquareIcon } from "lucide-react";
+import { createJsonApiInclusion } from "../../core";
+import { ModuleFactory } from "../../permissions";
+import { HandbookThread } from "./data/HandbookThread";
+
+/**
+ * A persisted handbook conversation.
+ *
+ * It carries no `pageUrl`: a thread is selected inside the ask surface
+ * (`/administration/handbook/chat`), never routed to on its own, and a
+ * `pageUrl` here would add a phantom entry to the RBAC path map.
+ *
+ * `lists` deliberately narrows to the title — the sidebar renders nothing else,
+ * and side-loading every message of every thread into the list payload is what
+ * the single-resource endpoint is for.
+ */
+export const HandbookThreadModule = (factory: ModuleFactory) =>
+  factory({
+    moduleId: "aea692c4-7163-49bd-9ddc-1052cc06fa14",
+    name: "handbookthreads",
+    model: HandbookThread,
+    icon: MessagesSquareIcon,
+    identifier: ["title"],
+    inclusions: {
+      lists: {
+        fields: [createJsonApiInclusion("handbookthreads", ["title"])],
+      },
+    },
+  });

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

@@ -0,0 +1,17 @@
+"use client";
+
+import HandbookContents from "../lists/HandbookContents";
+
+/**
+ * The administration route's entry point for the manual.
+ *
+ * `RoundPageContainer` moved down into `HandbookContents`, which is the only
+ * component that can supply it: the container's title bar reads its heading
+ * from `useSharedContext()`, so `HandbookProvider` has to wrap it, and the
+ * provider's `functions` (the ask launcher, Sincronizza and the status line)
+ * are built from the state `HandbookContents` holds. `HandbookAskContainer`
+ * composes its own surface the same way.
+ */
+export default function HandbookAdminContainer() {
+  return <HandbookContents />;
+}

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

@@ -0,0 +1,142 @@
+"use client";
+
+import { MessagesSquareIcon, Sparkles } from "lucide-react";
+import { useTranslations } from "next-intl";
+import { useMemo } from "react";
+
+import { RoundPageContainer } from "../../../../components/containers/RoundPageContainer";
+import { SectionHeader } from "../../../../components/typography";
+import { Modules } from "../../../../core";
+import { AssistantComposer } from "../../../assistant/components/parts/AssistantComposer";
+import { AssistantSidebar } from "../../../assistant/components/parts/AssistantSidebar";
+import { AssistantThread } from "../../../assistant/components/parts/AssistantThread";
+import { HandbookProvider } from "../../contexts/HandbookContext";
+import { useHandbookAsk } from "../../hooks/useHandbookAsk";
+
+/**
+ * The handbook ask surface.
+ *
+ * Composition is copied from `AssistantPageContainer` — the full-page assistant
+ * — top to bottom: the thread list lives in the page's details panel (which
+ * renders it on the trailing side) and the conversation fills the card. The
+ * transcript is rendered by the SAME components as every other chat in the
+ * product (`AssistantSidebar`, `AssistantThread`),
+ * which take their data as plain props and are typed against the structural
+ * `AssistantInterface` / `AssistantMessageInterface` that `HandbookThread` and
+ * `HandbookThreadMessage` implement.
+ *
+ * Two deliberate deviations from that reference, both forced by the data source:
+ *
+ * 1. It cannot MOUNT `AssistantPageContainer`, which reads
+ *    `useAssistantContext()`. That provider is bound to the `Assistant` entity,
+ *    which is company scoped, and a platform administrator has no company — so
+ *    the handbook owns its own threads, and the state that provider would hold
+ *    lives in `useHandbookAsk` — shared with the ask sheet, which is the same
+ *    conversation on a different surface.
+ * 2. The composer is the plain `AssistantComposer`, not the BlockNote one. The
+ *    BlockNote composer exists so a first message can carry `@`-mentions of
+ *    product entities; the handbook agent answers from documentation pages and
+ *    has no entities to mention, so that machinery would be dead weight.
+ *
+ * Every label is passed in from the `handbook.*` namespace. The assistant's own
+ * copy ("New assistant", "no assistants yet", "ask me about a matter, a client,
+ * a document…") is wrong on this surface, so the shared parts take optional
+ * label props that default to their existing text.
+ */
+
+type HandbookAskContainerProps = {
+  /** Thread to open on mount, when the route carries one. */
+  handbookThreadId?: string;
+};
+
+export function HandbookAskContainer({ handbookThreadId }: HandbookAskContainerProps = {}) {
+  const t = useTranslations();
+
+  // The conversation itself lives in `useHandbookAsk`, because the ask sheet
+  // holds the same one. The route keeps the default `syncUrl: true`, so the
+  // address bar still follows the open thread exactly as it did when this
+  // component owned the state.
+  const { threads, thread, messages, sending, ask, selectThread, startNew } = useHandbookAsk({ handbookThreadId });
+
+  const showThread = !!thread || sending || messages.length > 0;
+  // Memoised, and not as a micro-optimisation: it was a fresh object on every
+  // render being fed into RoundPageContainer, which 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={threads}
+          activeId={thread?.id}
+          onSelect={selectThread}
+          onNew={startNew}
+          newLabel={t("handbook.chat.new")}
+          emptyLabel={t("handbook.chat.empty_sidebar")}
+        />
+      </div>
+    ),
+    [selectThread, startNew, t, thread?.id, threads],
+  );
+
+  return (
+    // `RoundPageContainer` reads the page heading from the shared context, and
+    // `forceHeader` is what renders it — without a provider the hook throws.
+    // `HandbookProvider` is that provider for every handbook surface; the ask
+    // is the one that overrides the title, because it is a conversation about
+    // the manual rather than a page of it.
+    <HandbookProvider titleType={t("handbook.chat.title")}>
+      <RoundPageContainer
+        module={Modules.HandbookPage}
+        id={thread?.id}
+        fullWidth
+        forceHeader
+        defaultDetailsOpen
+        detailsTitle={t("handbook.chat.list_title")}
+        detailsIcon={<MessagesSquareIcon />}
+        details={details}
+      >
+        {/* No `rounded-lg border` here. `AssistantPageContainer` has them on
+            this wrapper, but RoundPageContainer already draws the card's border
+            around this child, so copying them doubles it. a360's own chat
+            content — ConversationMessageContainer — is a bare
+            `flex h-full w-full min-h-0 flex-col`, and that is the shape this
+            app's pages are built to. */}
+        <div className="flex h-full min-h-0 w-full flex-col overflow-hidden">
+          {showThread ? (
+            <>
+              {/* No per-thread header. `RoundPageContainer` already renders the
+                  page header above this card, and a second title row inside it
+                  is the double header. `AssistantThreadHeader` also carries
+                  rename/delete, which this surface does not offer —
+                  `ConversationMessageContainer` has no such row either. */}
+              <AssistantThread
+                messages={messages}
+                sending={sending}
+                status={t("handbook.chat.pending")}
+                onSelectFollowUp={ask}
+              />
+            </>
+          ) : (
+            <div className="flex flex-1 items-center justify-center p-10">
+              <div className="flex max-w-2xl 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>
+          )}
+          <AssistantComposer
+            onSend={ask}
+            disabled={sending}
+            placeholder={t("handbook.chat.placeholder")}
+            sendLabel={t("handbook.chat.ask")}
+          />
+        </div>
+      </RoundPageContainer>
+    </HandbookProvider>
+  );
+}

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