@carlonicora/nextjs-jsonapi 3.12.0 → 3.14.0

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

@@ -0,0 +1,288 @@
+import { render, screen, within } from "@testing-library/react";
+import { ReactNode } from "react";
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { configureI18n } from "../../../../../i18n";
+import { ApiRequestDataTypeInterface } from "../../../../../core/interfaces/ApiRequestDataTypeInterface";
+import { ModuleRegistry } from "../../../../../core/registry/ModuleRegistry";
+import { HandbookPageService } from "../../../data/HandbookPageService";
+import { HandbookSectionService } from "../../../data/HandbookSectionService";
+import HandbookPageContainer from "../HandbookPageContainer";
+
+// The fixtures are the contents surface's own (Task G), plus `content` for the
+// page under test. `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,
+      content: "# Reading order\n",
+    },
+    {
+      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,
+      content: "# Testing the API\n\n## What is mocked\n\nEverything.\n",
+    },
+    {
+      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,
+      content: "# Frontend models\n",
+    },
+  ],
+  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: { findOne: vi.fn(), findMany: vi.fn() },
+}));
+
+vi.mock("../../../data/HandbookSectionService", () => ({
+  HandbookSectionService: { findMany: vi.fn() },
+}));
+
+// The header is the provider's job (Task F) and the sheet is the ask surface's
+// (Task I). Neither is under test here, and both need providers this spec has
+// no reason to mount.
+vi.mock("../../../contexts/HandbookContext", () => ({
+  HandbookProvider: ({ children }: { children?: ReactNode }) => <>{children}</>,
+  useHandbookContext: () => ({}),
+}));
+
+vi.mock("../HandbookAskSheet", () => ({
+  HandbookAskSheet: () => <div data-testid="handbook-ask-sheet" />,
+}));
+
+// 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("HandbookPageContainer", () => {
+  beforeEach(() => {
+    vi.mocked(HandbookPageService.findOne)
+      .mockReset()
+      .mockImplementation(async ({ id }: { id: string }) => pages.find((page) => page.id === id) as any);
+    vi.mocked(HandbookPageService.findMany)
+      .mockReset()
+      .mockResolvedValue(pages as any);
+    vi.mocked(HandbookSectionService.findMany)
+      .mockReset()
+      .mockResolvedValue(sections as any);
+  });
+
+  it("renders the page title in the body once, and no path line", async () => {
+    render(<HandbookPageContainer handbookPageId="p2" />);
+
+    // The markdown's own H1 stays; the body's SectionHeader and path line are gone.
+    expect(await screen.findByRole("heading", { level: 1, name: "Testing the API" })).toBeInTheDocument();
+    expect(screen.queryByText("03-backend/testing.md")).not.toBeInTheDocument();
+  });
+
+  it("lists every page in the navigator with the current one marked", async () => {
+    render(<HandbookPageContainer handbookPageId="p2" />);
+
+    const nav = await screen.findByRole("navigation", { name: /contents/i });
+    expect(within(nav).getAllByRole("link")).toHaveLength(3);
+    expect(within(nav).getByRole("link", { current: "page" })).toHaveTextContent("Testing the API");
+  });
+
+  it("orders the navigator by section then order", async () => {
+    render(<HandbookPageContainer handbookPageId="p2" />);
+
+    const nav = await screen.findByRole("navigation", { name: /contents/i });
+    expect(
+      within(nav)
+        .getAllByRole("link")
+        .map((link) => link.textContent),
+    ).toEqual(["Reading order", "Frontend models", "Testing the API"]);
+  });
+
+  it("links the ordered neighbours", async () => {
+    render(<HandbookPageContainer handbookPageId="p2" />);
+
+    // "Frontend models" is the page before this one, so it renders twice: once
+    // in the navigator, once as the `previous` neighbour at the foot.
+    const links = await screen.findAllByRole("link", { name: /Frontend models/ });
+    expect(links).toHaveLength(2);
+    const previous = links.find((link) => link.textContent?.includes("handbook.reader.previous"));
+    expect(previous).toBeDefined();
+    expect(previous).toHaveAttribute("href", "/administration/handbook/p3");
+    // p2 is the last page in the order, so there is no `next` at all.
+    expect(screen.queryByText("handbook.reader.next")).not.toBeInTheDocument();
+  });
+
+  it("builds a heading index from the rendered markdown", async () => {
+    render(<HandbookPageContainer handbookPageId="p2" />);
+
+    // The visible label and the landmark name are the same key, which
+    // next-intl's spec mock renders verbatim.
+    const toc = await screen.findByRole("navigation", { name: /onThisPage/i });
+    expect(within(toc).getByRole("link", { name: "What is mocked" })).toHaveAttribute("href", "#what-is-mocked");
+  });
+
+  /**
+   * Indexed in English, shown translated. The reader has three surfaces that
+   * print handbook words — the body, the navigator and the prev/next pair — and
+   * all three resolve the same way.
+   *
+   * Only p2 (the page under test) and p3 (its `previous`) carry a translation,
+   * so one render proves both the translated and the fallback branch.
+   */
+  describe("display translation", () => {
+    const translated = pages.map((page) => {
+      if (page.id === "p2")
+        return {
+          ...page,
+          displayTitle: "Testare le API",
+          displayContent: "# Testare le API\n\n## Cosa è mockato\n\nTutto.\n",
+        };
+      if (page.id === "p3") return { ...page, displayTitle: "Modelli frontend" };
+      return page;
+    });
+
+    beforeEach(() => {
+      vi.mocked(HandbookPageService.findOne).mockImplementation(
+        async ({ id }: { id: string }) => translated.find((page) => page.id === id) as any,
+      );
+      vi.mocked(HandbookPageService.findMany).mockResolvedValue(translated as any);
+    });
+
+    it("renders the translated body", async () => {
+      render(<HandbookPageContainer handbookPageId="p2" />);
+
+      expect(await screen.findByRole("heading", { level: 1, name: "Testare le API" })).toBeInTheDocument();
+      expect(screen.queryByRole("heading", { level: 1, name: "Testing the API" })).not.toBeInTheDocument();
+    });
+
+    it("renders the English body for a page with no translation", async () => {
+      render(<HandbookPageContainer handbookPageId="p1" />);
+
+      expect(await screen.findByRole("heading", { level: 1, name: "Reading order" })).toBeInTheDocument();
+    });
+
+    it("labels the navigator entries with the translation, falling back per page", async () => {
+      render(<HandbookPageContainer handbookPageId="p2" />);
+
+      const nav = await screen.findByRole("navigation", { name: /contents/i });
+      // Still ordered by `section` then `order`, which stay English: only the
+      // labels changed.
+      expect(
+        within(nav)
+          .getAllByRole("link")
+          .map((link) => link.textContent),
+      ).toEqual(["Reading order", "Modelli frontend", "Testare le API"]);
+      expect(within(nav).getByRole("link", { current: "page" })).toHaveTextContent("Testare le API");
+    });
+
+    it("labels the previous neighbour with its translation", async () => {
+      render(<HandbookPageContainer handbookPageId="p2" />);
+
+      const links = await screen.findAllByRole("link", { name: /Modelli frontend/ });
+      const previous = links.find((link) => link.textContent?.includes("handbook.reader.previous"));
+      expect(previous).toBeDefined();
+      // The link still points at the same page: the translation changes the
+      // words, never the destination.
+      expect(previous).toHaveAttribute("href", "/administration/handbook/p3");
+    });
+
+    it("labels the navigator sections with their translation, falling back per section", async () => {
+      vi.mocked(HandbookSectionService.findMany).mockResolvedValue(
+        sections.map((section) =>
+          section.key === "03-backend" ? { ...section, displayTitle: "Backend (API)" } : section,
+        ) as any,
+      );
+
+      render(<HandbookPageContainer handbookPageId="p2" />);
+
+      const nav = await screen.findByRole("navigation", { name: /contents/i });
+      expect(
+        within(nav)
+          .getAllByRole("heading")
+          .map((heading) => heading.textContent),
+      ).toEqual(["Start here", "Framework", "Backend (API)"]);
+    });
+  });
+
+  it("keeps the not-found branch when the id resolves to nothing", async () => {
+    vi.mocked(HandbookPageService.findOne).mockResolvedValue(undefined as any);
+
+    render(<HandbookPageContainer handbookPageId="ghost" />);
+
+    expect(await screen.findByText("handbook.notFound")).toBeInTheDocument();
+    expect(screen.queryByRole("navigation", { name: /contents/i })).not.toBeInTheDocument();
+  });
+
+  it("still renders the navigator when the section load fails", async () => {
+    vi.mocked(HandbookSectionService.findMany).mockRejectedValue(new Error("500"));
+
+    render(<HandbookPageContainer handbookPageId="p2" />);
+
+    const nav = await screen.findByRole("navigation", { name: /contents/i });
+    expect(within(nav).getAllByRole("link")).toHaveLength(3);
+    // Raw section keys as headings, in key order.
+    expect(
+      within(nav)
+        .getAllByRole("heading")
+        .map((heading) => heading.textContent),
+    ).toEqual(["00-start-here", "02-framework", "03-backend"]);
+  });
+});

package/src/features/handbook/components/details/HandbookPageDetails.tsx

@@ -0,0 +1,52 @@
+"use client";
+
+import { ReactMarkdownContainer } from "../../../../components";
+import { handbookPageContent } from "../../data/handbookDisplay";
+import { HandbookPageInterface } from "../../data/HandbookPageInterface";
+
+type HandbookPageDetailsProps = {
+  handbookPage: HandbookPageInterface;
+};
+
+/**
+ * `content` is markdown read from a file and rendered read-only. It is NOT a
+ * BlockNote field: nothing edits it in the app, so no editor and no
+ * blocks-to-text conversion is involved.
+ *
+ * The title and the file path are NOT rendered here. The reader's header owns
+ * both — it names the section and the page — and repeating them above the
+ * markdown's own H1 printed the title twice on every page.
+ *
+ * The body comes from `handbookPageContent`, so a page whose translation the
+ * ingest matched renders in the reader's language and one without it falls back
+ * to the English file. This is the detail read, which is the only read that
+ * carries `displayContent` at all.
+ */
+/**
+ * The reading column's type scale.
+ *
+ * `ReactMarkdownContainer`'s `size="normal"` puts NO size class on `p` or `li`,
+ * so they inherit — and the app's root is 14px while the browser default the
+ * container's own headings are sized against is 16px. The body therefore
+ * rendered a step larger than every other piece of body copy in the product,
+ * which role 7 of the typography system puts at `text-sm`.
+ *
+ * `text-sm` on the wrapper fixes the inherited elements by cascade. The heading
+ * ladder has explicit classes and cannot cascade, so it is restated one step
+ * down — a `text-3xl` H1 belongs to a page that has no header above it, and
+ * this one is already titled twice over by the reader's header and breadcrumb.
+ *
+ * Scoped HERE rather than in the shared container on purpose: 23 other surfaces
+ * render markdown through it — judgements, law articles, documents, legal
+ * research reports — and changing its default would restyle all of them
+ * silently. That alignment is worth making, but as its own change.
+ */
+const READING_SCALE = "text-sm [&_h1]:text-2xl [&_h2]:text-xl [&_h3]:text-base [&_h4]:text-sm [&_table]:text-sm";
+
+export function HandbookPageDetails({ handbookPage }: HandbookPageDetailsProps) {
+  return (
+    <div className={READING_SCALE}>
+      <ReactMarkdownContainer content={handbookPageContent(handbookPage)} />
+    </div>
+  );
+}

package/src/features/handbook/components/details/HandbookPageNeighbours.tsx

@@ -0,0 +1,72 @@
+"use client";
+
+import { useTranslations } from "next-intl";
+import { useMemo } from "react";
+
+import { MicroLabel } from "../../../../components";
+import { Modules } from "../../../../core";
+import { usePageUrlGenerator } from "../../../../hooks";
+import { Link } from "../../../../shadcnui";
+import { handbookPageTitle } from "../../data/handbookDisplay";
+import { HandbookPageInterface } from "../../data/HandbookPageInterface";
+
+type HandbookPageNeighboursProps = {
+  pages: HandbookPageInterface[];
+  currentId: string;
+};
+
+/**
+ * Previous and next, at the foot of the page.
+ *
+ * Walks the same ordering the navigator renders — section key, then `order`,
+ * which is the repo-relative path — so reading straight through the manual with
+ * these two links reproduces the contents page from top to bottom. Below `md`
+ * the navigator is hidden and this pair is the only way forward that is not the
+ * breadcrumb.
+ *
+ * Nothing renders at either end of the list: no disabled control, no empty slot.
+ *
+ * The ordering is read off `section` and `order`, which stay English; only the
+ * two labels are translated.
+ */
+export function HandbookPageNeighbours({ pages, currentId }: HandbookPageNeighboursProps) {
+  const t = useTranslations();
+  const generateUrl = usePageUrlGenerator();
+
+  const { previous, next } = useMemo(() => {
+    const ordered = [...pages].sort((a, b) =>
+      `${a.section ?? ""}/${a.order ?? ""}`.localeCompare(`${b.section ?? ""}/${b.order ?? ""}`),
+    );
+    const index = ordered.findIndex((page) => page.id === currentId);
+    if (index === -1) return { previous: undefined, next: undefined };
+
+    return { previous: ordered[index - 1], next: ordered[index + 1] };
+  }, [pages, currentId]);
+
+  if (!previous && !next) return null;
+
+  return (
+    <div className="mt-8 grid gap-4 border-t pt-4 md:grid-cols-2">
+      {previous ? (
+        <Link
+          href={generateUrl({ page: Modules.HandbookPage, id: previous.id })}
+          className="flex flex-col gap-y-1 text-start"
+        >
+          <MicroLabel>{t("handbook.reader.previous")}</MicroLabel>
+          <span className="text-primary text-sm font-medium">{handbookPageTitle(previous)}</span>
+        </Link>
+      ) : (
+        <span />
+      )}
+      {next ? (
+        <Link
+          href={generateUrl({ page: Modules.HandbookPage, id: next.id })}
+          className="flex flex-col gap-y-1 text-end md:items-end"
+        >
+          <MicroLabel>{t("handbook.reader.next")}</MicroLabel>
+          <span className="text-primary text-sm font-medium">{handbookPageTitle(next)}</span>
+        </Link>
+      ) : null}
+    </div>
+  );
+}

package/src/features/handbook/components/details/HandbookPageToc.tsx

@@ -0,0 +1,165 @@
+"use client";
+
+import { List } from "lucide-react";
+import { useTranslations } from "next-intl";
+import { useCallback, useEffect, useState, type MouseEvent as ReactMouseEvent } from "react";
+
+import { MicroLabel } from "../../../../components";
+import { cn } from "../../../../utils/cn";
+
+type HandbookPageTocProps = {
+  /** The `id` of the element holding the rendered markdown. */
+  containerId: string;
+};
+
+type TocHeading = {
+  id: string;
+  text: string;
+  level: number;
+};
+
+/**
+ * The heading index of the page being read.
+ *
+ * Follows `HowToTableOfContents` (apps/web how-to detail): the same
+ * IntersectionObserver tracking, the same rootMargin, the same
+ * topmost-visible-wins rule and the same smooth scroll on click. Only the
+ * heading SOURCE differs — the how-to reads BlockNote blocks and assigns the
+ * ids itself, this one reads the ids `rehype-slug` already put on the rendered
+ * markdown, so the entries are anchors with a real `href` rather than buttons.
+ */
+export function HandbookPageToc({ containerId }: HandbookPageTocProps) {
+  const t = useTranslations();
+  const [activeId, setActiveId] = useState<string | null>(null);
+  const [headings, setHeadings] = useState<TocHeading[]>([]);
+  const [headingsWithIds, setHeadingsWithIds] = useState<Map<string, Element>>(new Map());
+
+  // Read the headings out of the rendered markdown, and re-read them whenever
+  // the container's content changes — a different page renders into the same
+  // container without this component ever unmounting.
+  useEffect(() => {
+    const contentPanel = document.getElementById(containerId);
+    if (!contentPanel) return;
+
+    const collect = () => {
+      const headingElements = contentPanel.querySelectorAll("h1, h2, h3");
+      const nextHeadings: TocHeading[] = [];
+      const nextMap = new Map<string, Element>();
+
+      headingElements.forEach((el) => {
+        if (!el.id) return;
+        nextHeadings.push({
+          id: el.id,
+          text: el.textContent ?? "",
+          level: Number(el.tagName.slice(1)),
+        });
+        nextMap.set(el.id, el);
+      });
+
+      setHeadings(nextHeadings);
+      setHeadingsWithIds(nextMap);
+    };
+
+    collect();
+
+    const observer = new MutationObserver(collect);
+    observer.observe(contentPanel, { childList: true, subtree: true });
+
+    return () => observer.disconnect();
+  }, [containerId]);
+
+  // Set up IntersectionObserver for scroll tracking
+  useEffect(() => {
+    if (headingsWithIds.size === 0) return;
+
+    /*
+      `root: null` — the VIEWPORT, deliberately.
+
+      The previous version looked for a `.overflow-y-auto` descendant of the
+      content panel and used that as the root. There is none: the element that
+      actually scrolls is an ANCESTOR (the page container's scroll body), so the
+      root fell back to the content panel itself, which never moves relative to
+      its own children. The observer therefore fired once on mount and never
+      again, and the only thing that ever changed the highlight was a click.
+
+      Viewport-relative intersection needs no knowledge of which ancestor
+      scrolls — the headings move through the viewport either way.
+    */
+    const observer = new IntersectionObserver(
+      (entries) => {
+        // Find the topmost visible heading
+        const visibleEntries = entries.filter((entry) => entry.isIntersecting);
+
+        if (visibleEntries.length > 0) {
+          // Sort by their position in the document and pick the first
+          const topEntry = visibleEntries.reduce((top, entry) => {
+            const topRect = top.boundingClientRect;
+            const entryRect = entry.boundingClientRect;
+            return entryRect.top < topRect.top ? entry : top;
+          });
+          setActiveId(topEntry.target.id);
+        }
+      },
+      {
+        root: null,
+        // The active band is the top tenth to top third of the viewport: a
+        // heading is "where you are" once it has reached reading position, not
+        // when it is still at the bottom edge.
+        rootMargin: "-10% 0px -70% 0px",
+        threshold: 0,
+      },
+    );
+
+    headingsWithIds.forEach((element) => {
+      observer.observe(element);
+    });
+
+    return () => observer.disconnect();
+  }, [containerId, headingsWithIds]);
+
+  const handleClick = useCallback(
+    (event: ReactMouseEvent<HTMLAnchorElement>, id: string) => {
+      const element = headingsWithIds.get(id);
+      if (!element) return;
+
+      event.preventDefault();
+      element.scrollIntoView({ behavior: "smooth", block: "start" });
+      // Deliberately NOT setActiveId(id). The highlight answers "where am I",
+      // and the observer answers that as the scroll lands. Setting it here made
+      // it answer "where did I click" instead, and it stuck there.
+    },
+    [headingsWithIds],
+  );
+
+  // Don't render if no headings
+  if (headings.length === 0) return null;
+
+  return (
+    <div className="flex flex-col gap-y-2">
+      <div className="flex items-center gap-2">
+        <List className="text-muted-foreground h-4 w-4" />
+        <MicroLabel>{t("handbook.reader.onThisPage")}</MicroLabel>
+      </div>
+      <nav aria-label={t("handbook.reader.onThisPage")} className="flex flex-col gap-y-0.5">
+        {headings.map((heading) => (
+          <a
+            key={heading.id}
+            href={`#${heading.id}`}
+            onClick={(event) => handleClick(event, heading.id)}
+            className={cn(
+              "hover:text-primary border-s-2 py-1 text-start text-xs transition-colors",
+              heading.level === 1 && "ps-3",
+              heading.level === 2 && "ps-5",
+              heading.level === 3 && "ps-7",
+              activeId === heading.id
+                ? "border-primary text-primary font-medium"
+                : "text-muted-foreground border-transparent",
+            )}
+          >
+            {heading.text}
+          </a>
+        ))}
+      </nav>
+    </div>
+  );
+}

package/src/features/handbook/components/forms/HandbookSyncButton.tsx

@@ -0,0 +1,43 @@
+"use client";
+
+import { useTranslations } from "next-intl";
+import { useState } from "react";
+
+import { Button } from "../../../../shadcnui";
+import { showError, showToast } from "../../../../utils/toast";
+import { HandbookPageService } from "../../data/HandbookPageService";
+
+type HandbookSyncButtonProps = {
+  refresh: () => Promise<void>;
+};
+
+/**
+ * The sync 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 HandbookSyncButton({ refresh }: HandbookSyncButtonProps) {
+  const t = useTranslations();
+  const [isSyncing, setIsSyncing] = useState(false);
+
+  const onSync = async () => {
+    setIsSyncing(true);
+    try {
+      await HandbookPageService.sync();
+      await refresh();
+      showToast(t(`handbook.synced`));
+    } catch {
+      // The most common failure is a consumer with no `handbook.path`
+      // configured, which the API answers with 400. Surface it and leave the
+      // list untouched.
+      showError(t(`handbook.syncFailed`));
+    } finally {
+      setIsSyncing(false);
+    }
+  };
+
+  return (
+    <Button onClick={onSync} disabled={isSyncing}>
+      {isSyncing ? t(`handbook.syncing`) : t(`handbook.sync`)}
+    </Button>
+  );
+}

package/src/features/handbook/components/forms/__tests__/HandbookSyncButton.spec.tsx

@@ -0,0 +1,42 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { HandbookPageService } from "../../../data/HandbookPageService";
+import HandbookSyncButton from "../HandbookSyncButton";
+
+vi.mock("../../../data/HandbookPageService", () => ({
+  HandbookPageService: { sync: vi.fn() },
+}));
+
+vi.mock("next-intl", () => ({
+  useTranslations: () => (key: string) => key,
+}));
+
+describe("HandbookSyncButton", () => {
+  beforeEach(() => {
+    vi.mocked(HandbookPageService.sync).mockReset().mockResolvedValue(undefined);
+  });
+
+  it("syncs, then refreshes the list", async () => {
+    const refresh = vi.fn().mockResolvedValue(undefined);
+    render(<HandbookSyncButton refresh={refresh} />);
+
+    await userEvent.click(screen.getByRole("button"));
+
+    await waitFor(() => expect(HandbookPageService.sync).toHaveBeenCalledTimes(1));
+    await waitFor(() => expect(refresh).toHaveBeenCalledTimes(1));
+  });
+
+  it("does not refresh when the sync fails, and re-enables itself", async () => {
+    vi.mocked(HandbookPageService.sync).mockRejectedValue(new Error("no handbook path configured"));
+    const refresh = vi.fn().mockResolvedValue(undefined);
+    render(<HandbookSyncButton refresh={refresh} />);
+
+    await userEvent.click(screen.getByRole("button"));
+
+    await waitFor(() => expect(HandbookPageService.sync).toHaveBeenCalledTimes(1));
+    expect(refresh).not.toHaveBeenCalled();
+    await waitFor(() => expect(screen.getByRole("button")).not.toBeDisabled());
+  });
+});

package/src/features/handbook/components/index.ts

@@ -0,0 +1,12 @@
+export { default as HandbookAdminContainer } from "./containers/HandbookAdminContainer";
+export { default as HandbookPageContainer } from "./containers/HandbookPageContainer";
+export * from "./containers/HandbookAskContainer";
+export * from "./containers/HandbookAskSheet";
+export * from "./details/HandbookPageDetails";
+export * from "./details/HandbookPageNeighbours";
+export * from "./details/HandbookPageToc";
+export * from "./parts/HandbookPageNavigator";
+export { default as HandbookSyncButton } from "./forms/HandbookSyncButton";
+export { default as HandbookContents } from "./lists/HandbookContents";
+export * from "./lists/HandbookSectionGroup";
+export * from "./parts/HandbookIndexStatus";