@carlonicora/nextjs-jsonapi 3.11.0 → 3.13.0

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

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

@@ -0,0 +1,131 @@
+import { render, screen } from "@testing-library/react";
+import { beforeAll, describe, expect, it, vi } from "vitest";
+
+import { useSharedContext } from "../../../../contexts";
+import { ApiRequestDataTypeInterface } from "../../../../core/interfaces/ApiRequestDataTypeInterface";
+import { ModuleRegistry } from "../../../../core/registry/ModuleRegistry";
+import { HandbookProvider, useHandbookContext } from "../HandbookContext";
+
+vi.mock("next-intl", () => ({
+  useTranslations: () => (key: string) => key,
+}));
+
+// The provider builds its breadcrumbs with `generateUrl({ page: Modules.HandbookPage })`,
+// and the `Modules` proxy throws for a key the registry does not hold. Registering is the
+// package's spec convention — copied from HandbookAskContainer.spec.tsx, which registers
+// the same module for the same reason.
+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);
+});
+
+function Probe() {
+  const { title, breadcrumbs } = useSharedContext();
+  return (
+    <>
+      <span data-testid="type">{String(title.type)}</span>
+      <span data-testid="element">{title.element ?? ""}</span>
+      <span data-testid="crumbs">{breadcrumbs.map((b) => b.name).join(" / ")}</span>
+    </>
+  );
+}
+
+describe("HandbookProvider", () => {
+  it("titles the contents surface with the handbook title and no element", () => {
+    render(
+      <HandbookProvider>
+        <Probe />
+      </HandbookProvider>,
+    );
+    expect(screen.getByTestId("type")).toHaveTextContent("handbook.title");
+    expect(screen.getByTestId("element")).toHaveTextContent("");
+  });
+
+  it("titles the reader with the section as type and the page as element", () => {
+    render(
+      <HandbookProvider
+        page={{ id: "p1", title: "Testing the API", section: "03-backend" } as any}
+        section={{ key: "03-backend", title: "Backend" } as any}
+      >
+        <Probe />
+      </HandbookProvider>,
+    );
+    expect(screen.getByTestId("type")).toHaveTextContent("Backend");
+    expect(screen.getByTestId("element")).toHaveTextContent("Testing the API");
+    expect(screen.getByTestId("crumbs")).toHaveTextContent("handbook.title / Testing the API");
+  });
+
+  it("falls back to the raw section key when no section resource resolved", () => {
+    render(
+      <HandbookProvider page={{ id: "p1", title: "X", section: "09-workflow" } as any}>
+        <Probe />
+      </HandbookProvider>,
+    );
+    expect(screen.getByTestId("type")).toHaveTextContent("09-workflow");
+  });
+
+  it("lets the ask surface override the type and passes functions through", () => {
+    function FunctionsProbe() {
+      const { title } = useSharedContext();
+      return <span data-testid="functions">{title.functions}</span>;
+    }
+
+    render(
+      <HandbookProvider titleType="handbook.chat.title" functions={<button type="button">ask</button>}>
+        <FunctionsProbe />
+      </HandbookProvider>,
+    );
+    expect(screen.getByTestId("functions")).toHaveTextContent("ask");
+  });
+
+  it("titles the reader with the translation when the page and section carry one", () => {
+    render(
+      <HandbookProvider
+        page={{ id: "p1", title: "Testing the API", displayTitle: "Testare le API", section: "03-backend" } as any}
+        section={{ key: "03-backend", title: "Backend", displayTitle: "Backend (API)" } as any}
+      >
+        <Probe />
+      </HandbookProvider>,
+    );
+    expect(screen.getByTestId("type")).toHaveTextContent("Backend (API)");
+    expect(screen.getByTestId("element")).toHaveTextContent("Testare le API");
+    expect(screen.getByTestId("crumbs")).toHaveTextContent("handbook.title / Testare le API");
+  });
+
+  it("falls back to the English title when neither carries a translation", () => {
+    render(
+      <HandbookProvider
+        page={{ id: "p1", title: "Testing the API", displayTitle: undefined, section: "03-backend" } as any}
+        section={{ key: "03-backend", title: "Backend", displayTitle: undefined } as any}
+      >
+        <Probe />
+      </HandbookProvider>,
+    );
+    expect(screen.getByTestId("type")).toHaveTextContent("Backend");
+    expect(screen.getByTestId("element")).toHaveTextContent("Testing the API");
+  });
+
+  it("exposes the page and section to useHandbookContext", () => {
+    function ContextProbe() {
+      const { page, section } = useHandbookContext();
+      return <span data-testid="context">{`${page?.title} / ${section?.title}`}</span>;
+    }
+
+    render(
+      <HandbookProvider
+        page={{ id: "p1", title: "Testing the API", section: "03-backend" } as any}
+        section={{ key: "03-backend", title: "Backend" } as any}
+      >
+        <ContextProbe />
+      </HandbookProvider>,
+    );
+    expect(screen.getByTestId("context")).toHaveTextContent("Testing the API / Backend");
+  });
+});

package/src/features/handbook/data/HandbookPage.spec.ts

@@ -0,0 +1,136 @@
+import { beforeAll, describe, expect, it } from "vitest";
+import { ApiRequestDataTypeInterface } from "../../../core/interfaces/ApiRequestDataTypeInterface";
+import { ModuleRegistry } from "../../../core/registry/ModuleRegistry";
+import { HandbookPage } from "./HandbookPage";
+
+// createJsonApi reads Modules.HandbookPage.name (resolved lazily via
+// ModuleRegistry), so the module must be registered before the model
+// serialises — mirrors the HowTo.spec setup convention in this package.
+const handbookPageModule: ApiRequestDataTypeInterface = {
+  name: "handbookpages",
+  model: HandbookPage,
+} as any;
+
+beforeAll(() => {
+  ModuleRegistry.register("HandbookPage", handbookPageModule);
+});
+
+describe("HandbookPage", () => {
+  it("rehydrates every attribute", () => {
+    const page = new HandbookPage().rehydrate({
+      jsonApi: {
+        id: "id-1",
+        type: "handbookpages",
+        attributes: {
+          path: "03-backend/module-anatomy.md",
+          title: "Module anatomy",
+          content: "# Module anatomy",
+          contentHash: "abc",
+          wordCount: 3,
+          aiStatus: "completed",
+        },
+      },
+    } as any);
+
+    expect(page.path).toBe("03-backend/module-anatomy.md");
+    expect(page.title).toBe("Module anatomy");
+    expect(page.content).toBe("# Module anatomy");
+    expect(page.contentHash).toBe("abc");
+    expect(page.wordCount).toBe(3);
+    expect(page.aiStatus).toBe("completed");
+  });
+
+  it("defaults a missing word count to zero and a missing status to undefined", () => {
+    const page = new HandbookPage().rehydrate({
+      jsonApi: {
+        id: "id-1",
+        type: "handbookpages",
+        attributes: { path: "a.md", title: "A", content: "#A", contentHash: "h" },
+      },
+    } as any);
+
+    expect(page.wordCount).toBe(0);
+    expect(page.aiStatus).toBeUndefined();
+  });
+
+  it("creates an identity-only JSON:API payload", () => {
+    const payload = new HandbookPage().createJsonApi({ id: "id-1" });
+    expect(payload.data.type).toBe("handbookpages");
+    expect(payload.data.id).toBe("id-1");
+    expect(payload.data.attributes).toEqual({});
+  });
+
+  it("rehydrates section, order and summary", () => {
+    const page = new HandbookPage().rehydrate({
+      jsonApi: {
+        type: "handbookpages",
+        id: "p1",
+        attributes: {
+          path: "03-backend/testing.md",
+          title: "Testing the API",
+          section: "03-backend",
+          order: "03-backend/testing.md",
+          summary: "The spec layout and what is mocked.",
+        },
+      },
+      included: [],
+    } as any);
+
+    expect(page.section).toBe("03-backend");
+    expect(page.order).toBe("03-backend/testing.md");
+    expect(page.summary).toBe("The spec layout and what is mocked.");
+  });
+
+  it("returns undefined for a missing summary", () => {
+    const page = new HandbookPage().rehydrate({
+      jsonApi: { type: "handbookpages", id: "p1", attributes: { title: "X" } },
+      included: [],
+    } as any);
+    expect(page.summary).toBeUndefined();
+  });
+
+  it("rehydrates the translation that travels beside the English original", () => {
+    const page = new HandbookPage().rehydrate({
+      jsonApi: {
+        type: "handbookpages",
+        id: "p1",
+        attributes: {
+          path: "03-backend/testing.md",
+          title: "Testing the API",
+          summary: "The spec layout and what is mocked.",
+          content: "# Testing the API",
+          displayTitle: "Testare le API",
+          displaySummary: "Come sono organizzati gli spec.",
+          displayContent: "# Testare le API",
+        },
+      },
+      included: [],
+    } as any);
+
+    // The translation lives on the SAME node, matched by `path` at ingest
+    // time: no second id, no locale in the payload.
+    expect(page.id).toBe("p1");
+    expect(page.displayTitle).toBe("Testare le API");
+    expect(page.displaySummary).toBe("Come sono organizzati gli spec.");
+    expect(page.displayContent).toBe("# Testare le API");
+    // The English original is still there, and `path` is untouched: ordering
+    // and grouping read it and must not move.
+    expect(page.title).toBe("Testing the API");
+    expect(page.path).toBe("03-backend/testing.md");
+  });
+
+  it("leaves an untranslated page's display fields undefined", () => {
+    const page = new HandbookPage().rehydrate({
+      jsonApi: {
+        type: "handbookpages",
+        id: "p1",
+        attributes: { title: "Testing the API", summary: "S", content: "# C" },
+      },
+      included: [],
+    } as any);
+
+    expect(page.displayTitle).toBeUndefined();
+    expect(page.displaySummary).toBeUndefined();
+    expect(page.displayContent).toBeUndefined();
+  });
+});

package/src/features/handbook/data/HandbookPage.ts

@@ -0,0 +1,99 @@
+import { AbstractApiData, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import { HandbookPageInput } from "./HandbookPageInput";
+import { HandbookPageInterface } from "./HandbookPageInterface";
+
+export class HandbookPage extends AbstractApiData implements HandbookPageInterface {
+  private _path?: string;
+  private _title?: string;
+  private _content?: string;
+  private _contentHash?: string;
+  private _wordCount?: number;
+  private _aiStatus?: string;
+  private _section?: string;
+  private _order?: string;
+  private _summary?: string;
+  private _displayTitle?: string;
+  private _displaySummary?: string;
+  private _displayContent?: string;
+
+  get path(): string {
+    return this._path ?? "";
+  }
+
+  get title(): string {
+    return this._title ?? "";
+  }
+
+  get content(): string {
+    return this._content ?? "";
+  }
+
+  get contentHash(): string {
+    return this._contentHash ?? "";
+  }
+
+  get wordCount(): number {
+    return this._wordCount ?? 0;
+  }
+
+  get aiStatus(): string | undefined {
+    return this._aiStatus;
+  }
+
+  get section(): string {
+    return this._section ?? "";
+  }
+
+  get order(): string {
+    return this._order ?? "";
+  }
+
+  get summary(): string | undefined {
+    return this._summary;
+  }
+
+  get displayTitle(): string | undefined {
+    return this._displayTitle;
+  }
+
+  get displaySummary(): string | undefined {
+    return this._displaySummary;
+  }
+
+  get displayContent(): string | undefined {
+    return this._displayContent;
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    this._path = data.jsonApi.attributes.path;
+    this._title = data.jsonApi.attributes.title;
+    this._content = data.jsonApi.attributes.content;
+    this._contentHash = data.jsonApi.attributes.contentHash;
+    this._wordCount = data.jsonApi.attributes.wordCount;
+    this._aiStatus = data.jsonApi.attributes.aiStatus;
+    this._section = data.jsonApi.attributes.section;
+    this._order = data.jsonApi.attributes.order;
+    this._summary = data.jsonApi.attributes.summary;
+    this._displayTitle = data.jsonApi.attributes.displayTitle;
+    this._displaySummary = data.jsonApi.attributes.displaySummary;
+    this._displayContent = data.jsonApi.attributes.displayContent;
+
+    return this;
+  }
+
+  createJsonApi(data: HandbookPageInput) {
+    const response: any = {
+      data: {
+        type: Modules.HandbookPage.name,
+        id: data.id,
+        attributes: {},
+        relationships: {},
+      },
+      included: [],
+    };
+
+    return response;
+  }
+}

package/src/features/handbook/data/HandbookPageFields.ts

@@ -0,0 +1,31 @@
+/**
+ * An ENUM, not a string array: `ContentListTable` indexes its column map by
+ * these members and `useDataListRetriever` keys rows by the id member, exactly
+ * as HowToFields does.
+ *
+ * `content` and `contentHash` are deliberately absent: they are detail-only,
+ * and a list of a thousand markdown files must not carry their bodies.
+ * `displayContent` — the same body in the reader's language — carries the same
+ * caveat: it names the field for the detail read and is deliberately NOT in the
+ * module's list inclusion.
+ *
+ * `section`, `order` and `summary` are list-safe for the opposite reason: they
+ * are the index fields the contents page groups, orders and describes pages by,
+ * so a list that omitted them could not render a table of contents at all.
+ * `displayTitle` and `displaySummary` travel with them: the manual is indexed
+ * in English and shown translated, so the contents page needs both halves.
+ */
+export enum HandbookPageFields {
+  handbookPageId = "handbookPageId",
+
+  path = "path",
+  title = "title",
+  displayTitle = "displayTitle",
+  section = "section",
+  order = "order",
+  summary = "summary",
+  displaySummary = "displaySummary",
+  displayContent = "displayContent",
+  wordCount = "wordCount",
+  aiStatus = "aiStatus",
+}

package/src/features/handbook/data/HandbookPageInput.ts

@@ -0,0 +1,8 @@
+/**
+ * Handbook pages are created by the backend ingest from files, never by a
+ * client. The input therefore carries identity only — it exists so the model
+ * satisfies AbstractApiData's contract, not because anything writes attributes.
+ */
+export type HandbookPageInput = {
+  id: string;
+};

package/src/features/handbook/data/HandbookPageInterface.ts

@@ -0,0 +1,29 @@
+import { ApiDataInterface } from "../../../core";
+
+export interface HandbookPageInterface extends ApiDataInterface {
+  get path(): string;
+  get title(): string;
+  get content(): string;
+  get contentHash(): string;
+  get wordCount(): number;
+  get aiStatus(): string | undefined;
+  /** The top-level directory of the documentation tree this page belongs to. */
+  get section(): string;
+  /** The repo-relative path; sorting on it reproduces filesystem order. */
+  get order(): string;
+  /** The one-line description the tree's README index gives this page, when it has one. */
+  get summary(): string | undefined;
+  /**
+   * The translated rendering of `title`, when the ingest matched a translation
+   * of this page's `path`. The manual is INDEXED in English and SHOWN in the
+   * reader's language, so every surface renders `displayTitle ?? title`.
+   */
+  get displayTitle(): string | undefined;
+  /** The translated `summary`. Absent when the page has no translation. */
+  get displaySummary(): string | undefined;
+  /**
+   * The translated body. Detail-only, exactly as `content` is: it is the whole
+   * markdown file, so it never travels in a list payload.
+   */
+  get displayContent(): string | undefined;
+}