@carlonicora/nextjs-jsonapi 3.12.0 → 3.13.0

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

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

@@ -0,0 +1,60 @@
+import { AbstractService, EndpointCreator, HttpMethod, Modules, NextRef, PreviousRef } from "../../../core";
+import { HandbookPageInterface } from "./HandbookPageInterface";
+
+export class HandbookPageService extends AbstractService {
+  /**
+   * `next` / `prev` are not optional extras: `useDataListRetriever` drives
+   * pagination by handing the cursor back here, so a findMany that drops them
+   * renders exactly one page and no navigation, however many rows exist.
+   * Mirrors HowToService.findMany.
+   */
+  static async findMany(
+    params: {
+      search?: string;
+      fetchAll?: boolean;
+      next?: NextRef;
+      prev?: PreviousRef;
+    } = {},
+  ): Promise<HandbookPageInterface[]> {
+    const endpoint = new EndpointCreator({ endpoint: Modules.HandbookPage });
+
+    if (params.fetchAll) endpoint.addAdditionalParam("fetchAll", "true");
+    if (params.search) endpoint.addAdditionalParam("search", params.search);
+    if (Modules.HandbookPage.inclusions?.lists?.fields)
+      endpoint.limitToFields(Modules.HandbookPage.inclusions.lists.fields);
+    if (Modules.HandbookPage.inclusions?.lists?.types)
+      endpoint.limitToType(Modules.HandbookPage.inclusions.lists.types);
+
+    return this.callApi({
+      type: Modules.HandbookPage,
+      method: HttpMethod.GET,
+      endpoint: endpoint.generate(),
+      next: params.next,
+    });
+  }
+
+  static async findOne(params: { id: string }): Promise<HandbookPageInterface> {
+    return this.callApi<HandbookPageInterface>({
+      type: Modules.HandbookPage,
+      method: HttpMethod.GET,
+      endpoint: new EndpointCreator({ endpoint: Modules.HandbookPage, id: params.id }).generate(),
+    });
+  }
+
+  /** POST /handbookpages/sync — replies 204; the caller refetches the list. */
+  static async sync(): Promise<void> {
+    await this.callApi({
+      type: Modules.HandbookPage,
+      method: HttpMethod.POST,
+      endpoint: new EndpointCreator({ endpoint: Modules.HandbookPage, id: "sync" }).generate(),
+    });
+  }
+
+  static async delete(params: { id: string }): Promise<void> {
+    await this.callApi({
+      type: Modules.HandbookPage,
+      method: HttpMethod.DELETE,
+      endpoint: new EndpointCreator({ endpoint: Modules.HandbookPage, id: params.id }).generate(),
+    });
+  }
+}

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

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+import { HandbookSection } from "./HandbookSection";
+
+describe("HandbookSection", () => {
+  it("rehydrates every attribute", () => {
+    const section = new HandbookSection().rehydrate({
+      jsonApi: {
+        type: "handbooksections",
+        id: "s1",
+        attributes: { key: "03-backend", title: "Backend", summary: "The API.", order: "03-backend" },
+      },
+      included: [],
+    } as any);
+
+    expect(section.key).toBe("03-backend");
+    expect(section.title).toBe("Backend");
+    expect(section.summary).toBe("The API.");
+    expect(section.order).toBe("03-backend");
+  });
+
+  it("defaults missing strings and leaves summary undefined", () => {
+    const section = new HandbookSection().rehydrate({
+      jsonApi: { type: "handbooksections", id: "s1", attributes: {} },
+      included: [],
+    } as any);
+
+    expect(section.key).toBe("");
+    expect(section.title).toBe("");
+    expect(section.summary).toBeUndefined();
+    expect(section.displayTitle).toBeUndefined();
+    expect(section.displaySummary).toBeUndefined();
+  });
+
+  it("rehydrates the translation beside the English original, leaving the key alone", () => {
+    const section = new HandbookSection().rehydrate({
+      jsonApi: {
+        type: "handbooksections",
+        id: "s1",
+        attributes: {
+          key: "03-backend",
+          title: "Backend",
+          summary: "The API.",
+          order: "03-backend",
+          displayTitle: "Backend (API)",
+          displaySummary: "Le API.",
+        },
+      },
+      included: [],
+    } as any);
+
+    expect(section.displayTitle).toBe("Backend (API)");
+    expect(section.displaySummary).toBe("Le API.");
+    // `key` and `order` are what pages are matched and sorted by; they stay
+    // English whatever the translation says.
+    expect(section.key).toBe("03-backend");
+    expect(section.order).toBe("03-backend");
+  });
+});

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

@@ -0,0 +1,73 @@
+import { AbstractApiData, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import { HandbookSectionInput } from "./HandbookSectionInput";
+import { HandbookSectionInterface } from "./HandbookSectionInterface";
+
+export class HandbookSection extends AbstractApiData implements HandbookSectionInterface {
+  private _key?: string;
+  private _title?: string;
+  private _summary?: string;
+  private _order?: string;
+  private _displayTitle?: string;
+  private _displaySummary?: string;
+
+  get key(): string {
+    return this._key ?? "";
+  }
+
+  get title(): string {
+    return this._title ?? "";
+  }
+
+  get summary(): string | undefined {
+    return this._summary;
+  }
+
+  get order(): string {
+    return this._order ?? "";
+  }
+
+  get displayTitle(): string | undefined {
+    return this._displayTitle;
+  }
+
+  get displaySummary(): string | undefined {
+    return this._displaySummary;
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    this._key = data.jsonApi.attributes.key;
+    this._title = data.jsonApi.attributes.title;
+    this._summary = data.jsonApi.attributes.summary;
+    this._order = data.jsonApi.attributes.order;
+    this._displayTitle = data.jsonApi.attributes.displayTitle;
+    this._displaySummary = data.jsonApi.attributes.displaySummary;
+
+    return this;
+  }
+
+  /**
+   * Nothing calls this: sections are read-only over HTTP and written only by
+   * the ingest. It exists because every model implements `createJsonApi()`, and
+   * a model that throws on serialisation is a trap for the next writer.
+   */
+  createJsonApi(data: HandbookSectionInput) {
+    const response: any = {
+      data: {
+        type: Modules.HandbookSection.name,
+        id: data.id,
+        attributes: {},
+        relationships: {},
+      },
+      included: [],
+    };
+
+    if (data.key !== undefined) response.data.attributes.key = data.key;
+    if (data.title !== undefined) response.data.attributes.title = data.title;
+    if (data.summary !== undefined) response.data.attributes.summary = data.summary;
+    if (data.order !== undefined) response.data.attributes.order = data.order;
+
+    return response;
+  }
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Handbook sections are written only by the backend ingest, which replaces
+ * every one of them on each sync. No client ever posts one; this type exists so
+ * the model can satisfy AbstractApiData's `createJsonApi()` contract.
+ */
+export type HandbookSectionInput = {
+  id: string;
+  key: string;
+  title: string;
+  summary?: string;
+  order: string;
+};

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

@@ -0,0 +1,26 @@
+import { ApiDataInterface } from "../../../core";
+
+/**
+ * One top-level directory of the configured documentation tree.
+ *
+ * A page names its section by `key`, not by edge, so this interface carries no
+ * relationships: the contents page reads sections and pages in two calls and
+ * groups them client side.
+ */
+export interface HandbookSectionInterface extends ApiDataInterface {
+  /** The directory name, e.g. `03-backend`. The natural key of the ingest. */
+  get key(): string;
+  /** The prettified `key`, or the README heading when the index names one. */
+  get title(): string;
+  /** The README's blurb for the section. Absent when the tree has no index. */
+  get summary(): string | undefined;
+  /** The `key`; sorting on it reproduces the directories' numeric order. */
+  get order(): string;
+  /**
+   * The translated rendering of `title`, when the index carries one. Every
+   * reader-facing surface renders `displayTitle ?? title`.
+   */
+  get displayTitle(): string | undefined;
+  /** The translated `summary`. Absent when the section has no translation. */
+  get displaySummary(): string | undefined;
+}