@carlonicora/nextjs-jsonapi 3.12.0 → 3.13.0

package/src/features/handbook/components/lists/__tests__/HandbookContents.spec.tsx

@@ -0,0 +1,247 @@
+import { render, screen, within } from "@testing-library/react";
+import { ReactNode } from "react";
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { ApiRequestDataTypeInterface } from "../../../../../core/interfaces/ApiRequestDataTypeInterface";
+import { ModuleRegistry } from "../../../../../core/registry/ModuleRegistry";
+import { configureI18n } from "../../../../../i18n";
+import { HandbookPageService } from "../../../data/HandbookPageService";
+import { HandbookSectionService } from "../../../data/HandbookSectionService";
+import HandbookContents from "../HandbookContents";
+
+// `vi.mock` factories are hoisted above every module-scope const, so the rows
+// come from `vi.hoisted()` rather than from a plain const.
+const { pages, sections } = vi.hoisted(() => ({
+  pages: [
+    {
+      id: "p1",
+      title: "Reading order",
+      section: "00-start-here",
+      order: "00-start-here/reading-order.md",
+      path: "00-start-here/reading-order.md",
+      summary: "The three paths.",
+      aiStatus: "completed",
+      wordCount: 10,
+    },
+    {
+      id: "p2",
+      title: "Testing the API",
+      section: "03-backend",
+      order: "03-backend/testing.md",
+      path: "03-backend/testing.md",
+      summary: undefined,
+      aiStatus: "failed",
+      wordCount: 20,
+    },
+    {
+      id: "p3",
+      title: "Frontend models",
+      section: "02-framework",
+      order: "02-framework/rulebook/frontend/01-models.md",
+      path: "02-framework/rulebook/frontend/01-models.md",
+      summary: "AbstractApiData.",
+      aiStatus: "completed",
+      wordCount: 30,
+    },
+  ],
+  sections: [
+    { id: "s1", key: "00-start-here", title: "Start here", summary: "Get the stack running.", order: "00-start-here" },
+    { id: "s2", key: "02-framework", title: "Framework", summary: undefined, order: "02-framework" },
+    { id: "s3", key: "03-backend", title: "Backend", summary: "The API.", order: "03-backend" },
+  ],
+}));
+
+vi.mock("../../../data/HandbookPageService", () => ({
+  HandbookPageService: { findMany: vi.fn(), sync: vi.fn() },
+}));
+
+vi.mock("../../../data/HandbookSectionService", () => ({
+  HandbookSectionService: { findMany: vi.fn() },
+}));
+
+// The sheet is the ask surface's (Task I). It is not under test here, and it
+// needs providers this spec has no reason to mount.
+vi.mock("../../containers/HandbookAskSheet", () => ({
+  HandbookAskSheet: () => <div data-testid="handbook-ask-sheet" />,
+}));
+
+// The suite-wide next-intl stub returns the key and drops the values, which
+// would hide the two numbers the status line exists to show. This one keeps
+// them, so `{count} pagine · sincronizzato {date}` is still asserted on the
+// numbers rather than on a translated string this package does not own.
+vi.mock("next-intl", () => {
+  const makeT = () => {
+    const t = (key: string, values?: Record<string, unknown>) =>
+      values ? `${key} ${Object.values(values).join(" ")}`.trimEnd() : key;
+    (t as any).has = () => true;
+    return t;
+  };
+  return {
+    useTranslations: () => makeT(),
+    useLocale: () => "en",
+    useNow: () => new Date(),
+    useTimeZone: () => "UTC",
+    useFormatter: () => ({
+      dateTime: () => "sync-date",
+      number: (value: unknown) => String(value),
+      relativeTime: () => "",
+    }),
+  };
+});
+
+// The header is the provider's job (Task F). Stubbed as
+// HandbookPageContainer.spec.tsx stubs it, except that this stub renders
+// `functions`: the ask launcher, Sincronizza and the status line are handed to
+// the header through that prop, so dropping it would delete half of this
+// component's output from the test.
+vi.mock("../../../contexts/HandbookContext", () => ({
+  HandbookProvider: ({ children, functions }: { children?: ReactNode; functions?: ReactNode }) => (
+    <>
+      <div data-testid="page-functions">{functions}</div>
+      {children}
+    </>
+  ),
+  useHandbookContext: () => ({}),
+}));
+
+// RoundPageContainer is page chrome — header, details panel, url rewriting.
+// Stubbed exactly as HandbookAskContainer.spec.tsx stubs it.
+vi.mock("../../../../../components/containers/RoundPageContainer", () => ({
+  RoundPageContainer: ({ children }: { children?: ReactNode }) => <div>{children}</div>,
+}));
+
+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);
+
+  // The package `Link` resolves the app's next-intl Link at runtime; without a
+  // configured i18n it throws rather than rendering an anchor.
+  configureI18n({
+    useRouter: () => ({
+      push: () => {},
+      replace: () => {},
+      back: () => {},
+      forward: () => {},
+      refresh: () => {},
+      prefetch: () => {},
+    }),
+    useTranslations: () => (key: string) => key,
+    usePathname: () => "/administration/handbook",
+    Link: ({ href, children, ...props }: any) => (
+      <a href={href} {...props}>
+        {children}
+      </a>
+    ),
+  });
+});
+
+describe("HandbookContents", () => {
+  beforeEach(() => {
+    vi.mocked(HandbookPageService.findMany)
+      .mockReset()
+      .mockResolvedValue(pages as any);
+    vi.mocked(HandbookSectionService.findMany)
+      .mockReset()
+      .mockResolvedValue(sections as any);
+  });
+
+  it("renders sections in order with their blurbs", async () => {
+    render(<HandbookContents />);
+    const headings = await screen.findAllByRole("heading", { level: 2 });
+    expect(headings.map((h) => h.textContent)).toEqual(["Start here", "Framework", "Backend"]);
+    expect(screen.getByText("Get the stack running.")).toBeInTheDocument();
+  });
+
+  it("renders a page summary when it has one and nothing when it does not", async () => {
+    render(<HandbookContents />);
+    expect(await screen.findByText("The three paths.")).toBeInTheDocument();
+    const row = screen.getByRole("link", { name: /Testing the API/ });
+    expect(within(row).queryByText("—")).not.toBeInTheDocument();
+    expect(row.textContent).toBe("Testing the API");
+  });
+
+  it("groups a nested page under its intermediate directory", async () => {
+    render(<HandbookContents />);
+    expect(await screen.findByText("rulebook / frontend")).toBeInTheDocument();
+  });
+
+  it("counts failures in the status line", async () => {
+    render(<HandbookContents />);
+    expect(await screen.findByText(/1/)).toBeInTheDocument();
+  });
+
+  it("renders no table", async () => {
+    render(<HandbookContents />);
+    await screen.findAllByRole("heading", { level: 2 });
+    expect(screen.queryByRole("table")).not.toBeInTheDocument();
+  });
+
+  /**
+   * The manual is INDEXED in English and SHOWN translated: every string on this
+   * surface prefers the translation that travels beside the English original,
+   * and falls back to the original when the ingest matched none.
+   *
+   * The fixtures are the suite's own, with a translation added to exactly one
+   * page and one section — so the same render proves both halves of the rule.
+   */
+  describe("display translation", () => {
+    const translatedPages = pages.map((page) =>
+      page.id === "p1" ? { ...page, displayTitle: "Ordine di lettura", displaySummary: "I tre percorsi." } : page,
+    );
+    const translatedSections = sections.map((section) =>
+      section.key === "00-start-here"
+        ? { ...section, displayTitle: "Da qui si parte", displaySummary: "Avvia lo stack." }
+        : section,
+    );
+
+    beforeEach(() => {
+      vi.mocked(HandbookPageService.findMany).mockResolvedValue(translatedPages as any);
+      vi.mocked(HandbookSectionService.findMany).mockResolvedValue(translatedSections as any);
+    });
+
+    it("renders a translated section heading and blurb, and the English ones where there is no translation", async () => {
+      render(<HandbookContents />);
+      const headings = await screen.findAllByRole("heading", { level: 2 });
+      expect(headings.map((h) => h.textContent)).toEqual(["Da qui si parte", "Framework", "Backend"]);
+      expect(screen.getByText("Avvia lo stack.")).toBeInTheDocument();
+      expect(screen.queryByText("Get the stack running.")).not.toBeInTheDocument();
+      // The untranslated section still reads in English.
+      expect(screen.getByText("The API.")).toBeInTheDocument();
+    });
+
+    it("renders a translated page row and falls back to English for an untranslated one", async () => {
+      render(<HandbookContents />);
+      expect(await screen.findByRole("link", { name: /Ordine di lettura/ })).toBeInTheDocument();
+      expect(screen.queryByRole("link", { name: /Reading order/ })).not.toBeInTheDocument();
+      expect(screen.getByText("I tre percorsi.")).toBeInTheDocument();
+      expect(screen.getByRole("link", { name: /Frontend models/ })).toBeInTheDocument();
+    });
+
+    it("orders sections and pages by the untranslated keys", async () => {
+      render(<HandbookContents />);
+      const headings = await screen.findAllByRole("heading", { level: 2 });
+      // `order` and `section` stay English, so the translated section keeps its
+      // place rather than sorting under its Italian initial.
+      expect(headings.map((h) => h.textContent)).toEqual(["Da qui si parte", "Framework", "Backend"]);
+      expect(await screen.findByText("rulebook / frontend")).toBeInTheDocument();
+    });
+  });
+
+  it("falls back to raw section keys when the section load fails", async () => {
+    vi.mocked(HandbookSectionService.findMany).mockRejectedValueOnce(new Error("500"));
+    render(<HandbookContents />);
+    const headings = await screen.findAllByRole("heading", { level: 2 });
+    expect(headings.map((h) => h.textContent)).toEqual(["00-start-here", "02-framework", "03-backend"]);
+    expect(screen.getByRole("link", { name: /Reading order/ })).toBeInTheDocument();
+  });
+});

package/src/features/handbook/components/parts/HandbookIndexStatus.tsx

@@ -0,0 +1,62 @@
+"use client";
+
+import { useFormatter, useTranslations } from "next-intl";
+import { useMemo } from "react";
+
+import { HandbookPageInterface } from "../../data/HandbookPageInterface";
+
+type HandbookIndexStatusProps = {
+  pages: HandbookPageInterface[];
+};
+
+/**
+ * `aiStatus` values written by the ingest. Only `failed` means the page is not
+ * answerable; `pending` and `in_progress` are a sync still running and say
+ * nothing about the index being wrong.
+ */
+const FAILURE_STATUSES = new Set(["failed", "error"]);
+
+/**
+ * The one line of index bookkeeping the reading surface keeps.
+ *
+ * Word counts and per-page AI badges left the contents page; how many pages
+ * there are and when they were last synced did not, because that is the one
+ * question the administrator who pressed Sincronizza actually has. Both values
+ * are derived from the loaded pages — nothing new is stored for either, and
+ * `updatedAt` is framework-managed.
+ */
+export function HandbookIndexStatus({ pages }: HandbookIndexStatusProps) {
+  const t = useTranslations();
+  const format = useFormatter();
+
+  const lastSynced = useMemo(() => {
+    let latest: Date | undefined = undefined;
+
+    for (const page of pages) {
+      const updatedAt = page.updatedAt;
+      if (!(updatedAt instanceof Date) || Number.isNaN(updatedAt.getTime())) continue;
+      if (!latest || updatedAt.getTime() > latest.getTime()) latest = updatedAt;
+    }
+
+    return latest;
+  }, [pages]);
+
+  const failures = useMemo(
+    () => pages.filter((page) => FAILURE_STATUSES.has((page.aiStatus ?? "").toLowerCase())).length,
+    [pages],
+  );
+
+  return (
+    <span className="text-muted-foreground text-xs tabular-nums">
+      {t("handbook.contents.status", {
+        count: pages.length,
+        date: lastSynced ? format.dateTime(lastSynced, { dateStyle: "medium" }) : "",
+      })}
+      {failures > 0 ? (
+        <span className="text-destructive ms-2 tabular-nums">
+          {t("handbook.contents.failures", { count: failures })}
+        </span>
+      ) : null}
+    </span>
+  );
+}

package/src/features/handbook/components/parts/HandbookPageNavigator.tsx

@@ -0,0 +1,143 @@
+"use client";
+
+import { BookOpenIcon } from "lucide-react";
+import { useTranslations } from "next-intl";
+import { useEffect, useMemo, useRef } from "react";
+
+import { MicroLabel } from "../../../../components";
+import { Modules } from "../../../../core";
+import { usePageUrlGenerator } from "../../../../hooks";
+import { Link } from "../../../../shadcnui";
+import { cn } from "../../../../utils/cn";
+import { handbookPageTitle, handbookSectionTitle } from "../../data/handbookDisplay";
+import { HandbookPageInterface } from "../../data/HandbookPageInterface";
+import { HandbookSectionInterface } from "../../data/HandbookSectionInterface";
+
+type HandbookPageNavigatorProps = {
+  pages: HandbookPageInterface[];
+  sections: HandbookSectionInterface[];
+  currentId: string;
+};
+
+/**
+ * The manual's section tree, beside the page being read.
+ *
+ * A list of links, NOT `RoundPageContainer`'s `layout="rail"`: the rail renders
+ * a `TabsContent` per tab, so 120 pages would mean 120 content nodes and a
+ * client-side tab switch. A manual wants 120 real, shareable URLs and a working
+ * back button, which is what an anchor gives and a tab does not.
+ *
+ * Degrades the same way the contents surface does: a page whose `section`
+ * matches no loaded section — or has none at all — lands in a trailing group,
+ * and if no sections loaded at all the distinct page keys are used as written.
+ */
+export function HandbookPageNavigator({ pages, sections, currentId }: HandbookPageNavigatorProps) {
+  const t = useTranslations();
+  const generateUrl = usePageUrlGenerator();
+
+  const groups = useMemo(() => {
+    const byKey = new Map<string, HandbookPageInterface[]>();
+    for (const page of pages) {
+      const key = page.section ?? "";
+      const bucket = byKey.get(key);
+      if (bucket) bucket.push(page);
+      else byKey.set(key, [page]);
+    }
+
+    for (const bucket of byKey.values()) bucket.sort((a, b) => (a.order ?? "").localeCompare(b.order ?? ""));
+
+    const ordered: { key: string; title: string; pages: HandbookPageInterface[] }[] = [];
+    const consumed = new Set<string>();
+
+    for (const section of sections) {
+      const sectionPages = byKey.get(section.key);
+      if (!sectionPages) continue;
+      consumed.add(section.key);
+      ordered.push({ key: section.key, title: handbookSectionTitle(section), pages: sectionPages });
+    }
+
+    // Whatever the loaded sections did not describe: an unknown key, an empty
+    // one, or every key when the section load failed outright.
+    const leftovers = [...byKey.keys()].filter((key) => !consumed.has(key)).sort((a, b) => a.localeCompare(b));
+
+    for (const key of leftovers)
+      ordered.push({
+        key: key.length > 0 ? key : "__untitled",
+        title: key.length > 0 ? key : t("handbook.sections.untitled"),
+        pages: byKey.get(key) ?? [],
+      });
+
+    return ordered;
+  }, [pages, sections, t]);
+
+  const currentRef = useRef<HTMLAnchorElement | null>(null);
+
+  /*
+    Bring the current page into view inside the rail — 120 entries means it is
+    usually below the fold, and a position marker nobody can see marks nothing.
+
+    Deliberately NOT `scrollIntoView`: that walks up every scrollable ancestor,
+    so it would scroll the page itself and land the reader halfway down the
+    article they just opened. Setting `scrollTop` on the rail moves the rail and
+    only the rail.
+  */
+  useEffect(() => {
+    const link = currentRef.current;
+    if (!link) return;
+
+    const rail = link.closest<HTMLElement>(".overflow-y-auto");
+    if (!rail) return;
+
+    rail.scrollTop = link.offsetTop - rail.clientHeight / 2 + link.clientHeight / 2;
+  }, [currentId, groups]);
+
+  if (groups.length === 0) return null;
+
+  // No `max-h` / `overflow` on the nav: the reader's rail wrapper is the sticky
+  // scroll container, and a second one nested inside it would trap the scroll
+  // in the wrong element.
+  /*
+    Deliberately the same treatment as `HandbookPageToc`: an icon and a
+    micro-label at the top, entries at `text-xs` on a `border-s-2` rail, and the
+    current one marked by turning that rail `border-primary` rather than by
+    growing.
+
+    The previous version gave the current page `text-primary font-medium` with
+    no size class, so it inherited the base size and rendered far larger than
+    its neighbours — the entry moved instead of being marked, and there was no
+    rail to show position at all. The two rails of this page are the same kind
+    of object and now read as one.
+  */
+  return (
+    <div className="flex flex-col gap-y-2">
+      <div className="flex items-center gap-2">
+        <BookOpenIcon className="text-muted-foreground h-4 w-4" />
+        <MicroLabel>{t("handbook.reader.contents")}</MicroLabel>
+      </div>
+      <nav aria-label={t("handbook.reader.contents")} className="flex flex-col gap-y-3">
+        {groups.map((group) => (
+          <div key={group.key} className="flex flex-col gap-y-0.5">
+            <MicroLabel className="ps-3">{group.title}</MicroLabel>
+            {group.pages.map((page) => {
+              const isCurrent = page.id === currentId;
+              return (
+                <Link
+                  key={page.id}
+                  ref={isCurrent ? currentRef : undefined}
+                  href={generateUrl({ page: Modules.HandbookPage, id: page.id })}
+                  aria-current={isCurrent ? "page" : undefined}
+                  className={cn(
+                    "hover:text-primary block border-s-2 py-1 ps-3 text-start text-xs leading-tight transition-colors",
+                    isCurrent ? "border-primary text-primary font-medium" : "text-muted-foreground border-transparent",
+                  )}
+                >
+                  {handbookPageTitle(page)}
+                </Link>
+              );
+            })}
+          </div>
+        ))}
+      </nav>
+    </div>
+  );
+}

package/src/features/handbook/contexts/HandbookContext.tsx

@@ -0,0 +1,109 @@
+"use client";
+
+import { useTranslations } from "next-intl";
+import { createContext, ReactNode, useContext } from "react";
+import { SharedProvider } from "../../../contexts";
+import { Modules } from "../../../core";
+import { usePageUrlGenerator } from "../../../hooks";
+import { BreadcrumbItemData } from "../../../interfaces";
+import type { HandbookPageInterface, HandbookSectionInterface } from "../data";
+import { handbookPageTitle, handbookSectionTitle } from "../data/handbookDisplay";
+
+/**
+ * The handbook's page context.
+ *
+ * The reader's header was an empty bar with a book icon in it: the feature
+ * shipped no provider, and `RoundPageContainerTitle` reads its heading from
+ * `useSharedContext().title`
+ * (components/containers/RoundPageContainerTitle.tsx). With nothing supplying
+ * that context there was no title, no breadcrumb and no way back — so the page
+ * title was printed a second time inside the body instead.
+ *
+ * This is the provider every other feature already has, copied from
+ * `RoleProvider` (features/role/contexts/RoleContext.tsx): a `breadcrumb()`, a
+ * `title()`, and `SharedProvider` wrapping the feature's own context. Every
+ * handbook surface — contents, reader, ask — mounts it, so all three get the
+ * same header for free.
+ */
+
+interface HandbookContextType {
+  page: HandbookPageInterface | undefined;
+  section: HandbookSectionInterface | undefined;
+}
+
+const HandbookContext = createContext<HandbookContextType | undefined>(undefined);
+
+type HandbookProviderProps = {
+  children: ReactNode;
+  /** Undefined on the contents and ask surfaces. */
+  page?: HandbookPageInterface;
+  /** The page's section, when one is loaded and resolvable. */
+  section?: HandbookSectionInterface;
+  /** Rendered into `title.functions`. */
+  functions?: ReactNode;
+  /** Overrides the default `title.type`. Used by the ask surface. */
+  titleType?: string;
+};
+
+export const HandbookProvider = ({ children, page, section, functions, titleType }: HandbookProviderProps) => {
+  const generateUrl = usePageUrlGenerator();
+  const t = useTranslations();
+
+  const breadcrumb = () => {
+    const response: BreadcrumbItemData[] = [];
+
+    response.push({
+      name: t(`handbook.title`),
+      href: generateUrl({ page: Modules.HandbookPage }),
+    });
+
+    if (page)
+      response.push({
+        name: handbookPageTitle(page),
+        href: generateUrl({ page: Modules.HandbookPage, id: page.id }),
+      });
+
+    return response;
+  };
+
+  const title = () => {
+    const response: any = {
+      // The reader is titled by where the page sits, not by the manual it
+      // belongs to: the section is the `type` and the page is the `element`,
+      // the same split every entity detail page in the product uses. Sections
+      // are loaded as their own resource, so a page whose section has not
+      // resolved falls back to the raw key it carries — and the key is the
+      // directory name, which is not translated and never was.
+      type: titleType ?? (page ? (section ? handbookSectionTitle(section) : page.section) : t(`handbook.title`)),
+    };
+
+    if (page) {
+      response.element = handbookPageTitle(page);
+    }
+
+    if (functions) response.functions = functions;
+
+    return response;
+  };
+
+  return (
+    <SharedProvider value={{ breadcrumbs: breadcrumb(), title: title() }}>
+      <HandbookContext.Provider
+        value={{
+          page: page,
+          section: section,
+        }}
+      >
+        {children}
+      </HandbookContext.Provider>
+    </SharedProvider>
+  );
+};
+
+export const useHandbookContext = (): HandbookContextType => {
+  const context = useContext(HandbookContext);
+  if (context === undefined) {
+    throw new Error("useHandbookContext must be used within a HandbookProvider");
+  }
+  return context;
+};