@carlonicora/nextjs-jsonapi 3.12.0 → 3.13.0

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";

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

@@ -0,0 +1,196 @@
+"use client";
+
+import { useTranslations } from "next-intl";
+import { useCallback, useEffect, useMemo, useState } from "react";
+
+import { RoundPageContainer } from "../../../../components/containers/RoundPageContainer";
+import { Modules } from "../../../../core";
+import { HandbookProvider } from "../../contexts/HandbookContext";
+import { handbookSectionSummary, handbookSectionTitle } from "../../data/handbookDisplay";
+import { HandbookPageInterface } from "../../data/HandbookPageInterface";
+import { HandbookPageService } from "../../data/HandbookPageService";
+import { HandbookSectionInterface } from "../../data/HandbookSectionInterface";
+import { HandbookSectionService } from "../../data/HandbookSectionService";
+import { HandbookAskSheet } from "../containers/HandbookAskSheet";
+import HandbookSyncButton from "../forms/HandbookSyncButton";
+import { HandbookIndexStatus } from "../parts/HandbookIndexStatus";
+import { HandbookSectionGroup } from "./HandbookSectionGroup";
+
+type RenderedSection = {
+  key: string;
+  title: string;
+  summary?: string;
+  pages: HandbookPageInterface[];
+};
+
+/**
+ * The contents surface: the manual's table of contents, replacing the four
+ * column table of indexed files.
+ *
+ * It owns `RoundPageContainer` rather than being handed one, because
+ * `RoundPageContainerTitle` reads its heading from `useSharedContext()` and the
+ * provider that supplies it therefore has to be an ANCESTOR of the container —
+ * exactly the composition `HandbookAskContainer` already uses. See the
+ * hand-off note: the plan put the provider inside the container, which throws.
+ */
+export default function HandbookContents() {
+  const t = useTranslations();
+
+  const [pages, setPages] = useState<HandbookPageInterface[]>([]);
+  const [sections, setSections] = useState<HandbookSectionInterface[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+  const [reloadToken, setReloadToken] = useState(0);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    const load = async () => {
+      setIsLoading(true);
+
+      // The two loads are INDEPENDENT on purpose. A failed section read must
+      // not take the pages down with it: without sections the contents page
+      // falls back to the raw section keys, which is exactly what an nja
+      // application with no README index renders anyway.
+      const loadedPages = HandbookPageService.findMany({ fetchAll: true })
+        .then((result) => {
+          if (!cancelled) setPages(result ?? []);
+        })
+        .catch(() => {
+          if (!cancelled) setPages([]);
+        });
+
+      const loadedSections = HandbookSectionService.findMany()
+        .then((result) => {
+          if (!cancelled) setSections(result ?? []);
+        })
+        .catch(() => {
+          if (!cancelled) setSections([]);
+        });
+
+      await Promise.allSettled([loadedPages, loadedSections]);
+      if (!cancelled) setIsLoading(false);
+    };
+
+    void load();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [reloadToken]);
+
+  /** `HandbookSyncButton` awaits this before it toasts; re-running the effect refetches both resources. */
+  const refresh = useCallback(async () => {
+    setReloadToken((token) => token + 1);
+  }, []);
+
+  const renderedSections = useMemo(
+    () => buildSections({ pages, sections, untitled: t("handbook.sections.untitled") }),
+    [pages, sections, t],
+  );
+
+  return (
+    <HandbookProvider
+      functions={
+        <>
+          <HandbookAskSheet />
+          <HandbookSyncButton refresh={refresh} />
+          <HandbookIndexStatus pages={pages} />
+        </>
+      }
+    >
+      {/*
+        NOT `fullWidth`. That flag strips the container's `mx-auto max-w-6xl`
+        and its padding (RoundPageContainer.tsx:477-484) — it exists for the
+        edge-to-edge table this page replaced. A contents page is prose: it
+        wants the same centred, padded column every other non-table page in the
+        app uses, and a summary line running to 1900px is unreadable.
+      */}
+      <RoundPageContainer module={Modules.HandbookPage} forceHeader>
+        {isLoading ? null : renderedSections.length === 0 ? (
+          <span className="text-muted-foreground text-sm">{t("handbook.empty")}</span>
+        ) : (
+          <div className="flex w-full flex-col gap-10">
+            {renderedSections.map((section) => (
+              <HandbookSectionGroup
+                key={section.key}
+                title={section.title}
+                summary={section.summary}
+                pages={section.pages}
+              />
+            ))}
+          </div>
+        )}
+      </RoundPageContainer>
+    </HandbookProvider>
+  );
+}
+
+/**
+ * Turns the two loaded lists into the sections the page renders, in order.
+ *
+ * Three degradations, all of them load-bearing:
+ *
+ * 1. No sections loaded — the endpoint failed, or the application has no
+ *    README index — falls back to the distinct `section` values of the pages,
+ *    sorted, with the raw key as the heading and no blurb.
+ * 2. A section declared by the index but matching no page renders with its
+ *    blurb and an empty list. Visible drift beats a silently dropped heading.
+ * 3. A page whose `section` is empty or matches no loaded section lands in a
+ *    trailing group. A file at the root of the tree is one of those.
+ *
+ * The grouping and both sorts read `section`, `order` and `path`, which stay
+ * English: the manual is indexed in English and only shown translated. The two
+ * strings a section actually prints go through the display helpers, so a
+ * translated section renders translated and an untranslated one renders the
+ * English original it was indexed under.
+ */
+function buildSections(params: {
+  pages: HandbookPageInterface[];
+  sections: HandbookSectionInterface[];
+  untitled: string;
+}): RenderedSection[] {
+  const byOrder = (a: string, b: string) => a.localeCompare(b);
+
+  const ordered: { key: string; title: string; summary?: string }[] =
+    params.sections.length > 0
+      ? [...params.sections]
+          .sort((a, b) => byOrder(a.order || a.key, b.order || b.key))
+          .map((section) => ({
+            key: section.key,
+            title: handbookSectionTitle(section) || section.key,
+            summary: handbookSectionSummary(section),
+          }))
+      : Array.from(new Set(params.pages.map((page) => page.section).filter((key) => !!key)))
+          .sort(byOrder)
+          .map((key) => ({ key, title: key }));
+
+  const known = new Set(ordered.map((section) => section.key));
+
+  const grouped = new Map<string, HandbookPageInterface[]>();
+  const leftovers: HandbookPageInterface[] = [];
+
+  for (const page of params.pages) {
+    const key = page.section;
+    if (!key || !known.has(key)) {
+      leftovers.push(page);
+      continue;
+    }
+
+    const existing = grouped.get(key);
+    if (existing) existing.push(page);
+    else grouped.set(key, [page]);
+  }
+
+  const sortPages = (pages: HandbookPageInterface[]) =>
+    [...pages].sort((a, b) => byOrder(a.order || a.path || a.title, b.order || b.path || b.title));
+
+  const response: RenderedSection[] = ordered.map((section) => ({
+    ...section,
+    pages: sortPages(grouped.get(section.key) ?? []),
+  }));
+
+  if (leftovers.length > 0)
+    response.push({ key: "", title: params.untitled, summary: undefined, pages: sortPages(leftovers) });
+
+  return response;
+}

package/src/features/handbook/components/lists/HandbookSectionGroup.tsx

@@ -0,0 +1,153 @@
+"use client";
+
+import { useMemo } from "react";
+
+import { MicroLabel, SectionHeader } from "../../../../components/typography";
+import { Modules } from "../../../../core";
+import { usePageUrlGenerator } from "../../../../hooks";
+import { Link } from "../../../../shadcnui";
+import { handbookPageSummary, handbookPageTitle } from "../../data/handbookDisplay";
+import { HandbookPageInterface } from "../../data/HandbookPageInterface";
+
+type HandbookSectionGroupProps = {
+  /** Rendered as the section's `h2`. Already prettified and translated by the caller. */
+  title: string;
+  /** The README blurb for the section, already translated by the caller. */
+  summary?: string;
+  /** The section's pages, already sorted by `order` by the caller. */
+  pages: HandbookPageInterface[];
+};
+
+/**
+ * One section of the contents page: a heading, its blurb, and its pages.
+ *
+ * A page whose path nests below the section's own directory
+ * (`02-framework/rulebook/frontend/01-models.md` inside `02-framework`) is not
+ * a peer of the section's direct pages, so it renders under a micro-label
+ * naming the intermediate directories. The nesting is read off the path rather
+ * than stored, because the filesystem is the only place it is declared.
+ */
+export function HandbookSectionGroup({ title, summary, pages }: HandbookSectionGroupProps) {
+  const generateUrl = usePageUrlGenerator();
+
+  const { direct, nested } = useMemo(() => splitByNesting(pages), [pages]);
+
+  return (
+    <section className="flex flex-col gap-4">
+      {/*
+        The rule belongs to the heading block, not between the sections: it
+        marks where a section starts, so the generous gap above it reads as
+        separation and the tight gap below it as belonging.
+      */}
+      <div className="flex flex-col gap-1 border-b pb-3">
+        <SectionHeader level={2}>{title}</SectionHeader>
+        {summary ? <p className="text-muted-foreground text-sm">{summary}</p> : null}
+      </div>
+
+      {direct.length > 0 ? <HandbookPageRows pages={direct} generateUrl={generateUrl} /> : null}
+
+      {nested.map((group) => (
+        <div key={group.label} className="flex flex-col gap-1.5 pt-2">
+          <MicroLabel>{group.label}</MicroLabel>
+          <HandbookPageRows pages={group.pages} generateUrl={generateUrl} />
+        </div>
+      ))}
+    </section>
+  );
+}
+
+function HandbookPageRows({
+  pages,
+  generateUrl,
+}: {
+  pages: HandbookPageInterface[];
+  generateUrl: ReturnType<typeof usePageUrlGenerator>;
+}) {
+  return (
+    <ul className="divide-border/60 flex flex-col divide-y">
+      {pages.map((page) => {
+        // The translation when the ingest matched one, the English original
+        // when it did not. Resolved once per row rather than per element.
+        const summary = handbookPageSummary(page);
+
+        return (
+          <li key={page.id}>
+            {/*
+              The whole row is the link, not just the title: the summary describes
+              the same destination, and a second click target beside it would be a
+              second thing to aim at for no second outcome.
+
+              `text-sm` on the title and `text-xs` on the summary, not the
+              inherited base size — a row is a detail pair (roles 13 and 12), and
+              at base size it competed with the section heading above it instead
+              of sitting under it.
+            */}
+            <Link
+              href={generateUrl({ page: Modules.HandbookPage, id: page.id })}
+              className="hover:bg-muted/40 -mx-2 block rounded-md px-2 py-2"
+            >
+              <span className="text-primary block text-sm font-medium">{handbookPageTitle(page)}</span>
+              {summary ? (
+                <span className="text-muted-foreground mt-0.5 block text-xs font-normal">{sentenceCase(summary)}</span>
+              ) : null}
+            </Link>
+          </li>
+        );
+      })}
+    </ul>
+  );
+}
+
+/**
+ * The README writes each summary as a continuation of its link — "— boot, log
+ * in, create a proceeding" — so pasted in raw every row starts lowercase. Here
+ * the summary is a sentence of its own and reads as one.
+ *
+ * Only an ASCII letter is raised: several summaries open with a backtick
+ * (`` `defineEntity()` and everything derived from it ``) or a quotation mark,
+ * and those must survive untouched.
+ */
+function sentenceCase(summary: string): string {
+  const first = summary.charAt(0);
+  if (first < "a" || first > "z") return summary;
+  return first.toUpperCase() + summary.slice(1);
+}
+
+/**
+ * Splits a section's pages into the ones that sit directly in its directory and
+ * the ones that sit in a directory below it, keyed by the intermediate path.
+ *
+ * `03-backend/testing.md` is direct. `02-framework/rulebook/frontend/01-models.md`
+ * belongs to the group `rulebook / frontend`. The groups come out in path order
+ * and always after the direct pages, so a section reads as its own pages first
+ * and its sub-topics after.
+ */
+function splitByNesting(pages: HandbookPageInterface[]): {
+  direct: HandbookPageInterface[];
+  nested: { label: string; pages: HandbookPageInterface[] }[];
+} {
+  const direct: HandbookPageInterface[] = [];
+  const groups = new Map<string, HandbookPageInterface[]>();
+
+  for (const page of pages) {
+    const segments = (page.order || page.path || "").split("/").filter((segment) => segment.length > 0);
+    // Drop the filename, then the section's own directory.
+    const intermediate = segments.slice(0, -1).slice(1);
+
+    if (intermediate.length === 0) {
+      direct.push(page);
+      continue;
+    }
+
+    const label = intermediate.join(" / ");
+    const existing = groups.get(label);
+    if (existing) existing.push(page);
+    else groups.set(label, [page]);
+  }
+
+  const nested = Array.from(groups.entries())
+    .sort((a, b) => a[0].localeCompare(b[0]))
+    .map(([label, groupPages]) => ({ label, pages: groupPages }));
+
+  return { direct, nested };
+}