@carlonicora/nextjs-jsonapi 1.109.0 → 1.111.0

package/src/features/help/components/mdx/Video.tsx

@@ -1,8 +0,0 @@
-export function Video({ src, poster }: { src: string; poster?: string }) {
-  const url = src.startsWith("/") ? src : `/help-assets/${src}`;
-  return (
-    <video controls preload="metadata" poster={poster} className="my-4 w-full rounded-md ring-1 ring-border">
-      <source src={url} />
-    </video>
-  );
-}

package/src/features/help/components/mdx/mdx-server-components.ts

@@ -1,23 +0,0 @@
-// Server-safe subset of MDX_COMPONENTS used by `renderHelpArticle`.
-// Mirrors `mdxComponents.ts` but EXCLUDES `Related` (which is a client
-// component that uses `useHelp` + `usePageUrlGenerator`). Server-side rendering
-// of `<Related>` would require passing the manifest by prop, which the standard
-// MDX components map cannot do — articles that need related links should be
-// extended via a server-side render hook rather than the MDX shortcode.
-
-import { Callout } from "./Callout";
-import { Steps, Step } from "./Steps";
-import { Screenshot } from "./Screenshot";
-import { EntityRef } from "./EntityRef";
-import { KeyBinding } from "./KeyBinding";
-import { Video } from "./Video";
-
-export const MDX_SERVER_COMPONENTS = {
-  Callout,
-  Steps,
-  Step,
-  Screenshot,
-  EntityRef,
-  KeyBinding,
-  Video,
-} as const;

package/src/features/help/components/mdx/mdxComponents.ts

@@ -1,9 +0,0 @@
-import { Callout } from "./Callout";
-import { Steps, Step } from "./Steps";
-import { Screenshot } from "./Screenshot";
-import { EntityRef } from "./EntityRef";
-import { KeyBinding } from "./KeyBinding";
-import { Video } from "./Video";
-import { Related } from "./Related";
-
-export const MDX_COMPONENTS = { Callout, Steps, Step, Screenshot, EntityRef, KeyBinding, Video, Related };

package/src/features/help/hooks/useHelpArticle.ts

@@ -1,7 +0,0 @@
-"use client";
-import { useHelp } from "../contexts/HelpContext";
-import { findHelpArticle } from "../utils/helpNavigation";
-
-export function useHelpArticle(mode: string, slug: string) {
-  return findHelpArticle(useHelp().manifest, mode, slug);
-}

package/src/features/help/hooks/useHelpManifest.ts

@@ -1,5 +0,0 @@
-"use client";
-import { useHelp } from "../contexts/HelpContext";
-export function useHelpManifest() {
-  return useHelp().manifest;
-}

package/src/features/help/server/__tests__/createHelpAssetRouteHandler.spec.ts

@@ -1,43 +0,0 @@
-import { describe, it, expect, beforeAll, afterAll } from "vitest";
-import { mkdtemp, writeFile, mkdir, rm } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { createHelpAssetRouteHandler } from "../createHelpAssetRouteHandler";
-
-describe("createHelpAssetRouteHandler", () => {
-  let srcRoot: string;
-
-  beforeAll(async () => {
-    srcRoot = await mkdtemp(join(tmpdir(), "help-assets-"));
-    await mkdir(srcRoot, { recursive: true });
-    await writeFile(join(srcRoot, "ok.png"), Buffer.from([0x89, 0x50, 0x4e, 0x47]));
-  });
-  afterAll(async () => {
-    await rm(srcRoot, { recursive: true, force: true });
-  });
-
-  it("returns 200 with correct MIME for an existing PNG", async () => {
-    const GET = createHelpAssetRouteHandler({ srcRoot });
-    const res = await GET(new Request("http://localhost/help-assets/ok.png"), {
-      params: Promise.resolve({ path: ["ok.png"] }),
-    });
-    expect(res.status).toBe(200);
-    expect(res.headers.get("Content-Type")).toBe("image/png");
-  });
-
-  it("returns 404 for missing files", async () => {
-    const GET = createHelpAssetRouteHandler({ srcRoot });
-    const res = await GET(new Request("http://localhost/help-assets/missing.png"), {
-      params: Promise.resolve({ path: ["missing.png"] }),
-    });
-    expect(res.status).toBe(404);
-  });
-
-  it("sanitizes path traversal attempts", async () => {
-    const GET = createHelpAssetRouteHandler({ srcRoot });
-    const res = await GET(new Request("http://localhost/help-assets/etc/passwd"), {
-      params: Promise.resolve({ path: ["..", "..", "etc", "passwd"] }),
-    });
-    expect(res.status).toBe(404);
-  });
-});

package/src/features/help/server/createHelpAssetRouteHandler.ts

@@ -1,35 +0,0 @@
-import { NextResponse } from "next/server";
-import { readFile, stat } from "node:fs/promises";
-import { join } from "node:path";
-
-const MIME: Record<string, string> = {
-  ".png": "image/png",
-  ".jpg": "image/jpeg",
-  ".jpeg": "image/jpeg",
-  ".webp": "image/webp",
-  ".gif": "image/gif",
-  ".svg": "image/svg+xml",
-  ".mp4": "video/mp4",
-  ".webm": "video/webm",
-};
-
-export function createHelpAssetRouteHandler({ srcRoot }: { srcRoot: string }) {
-  return async function GET(_req: Request, { params }: { params: Promise<{ path: string[] }> }) {
-    const { path } = await params;
-    const safe = path.filter((p) => p !== ".." && !p.includes("/")).join("/");
-    const filePath = join(srcRoot, safe);
-    try {
-      const s = await stat(filePath);
-      if (!s.isFile()) return new NextResponse("Not found", { status: 404 });
-      const ext = filePath.toLowerCase().slice(filePath.lastIndexOf("."));
-      const mime = MIME[ext] ?? "application/octet-stream";
-      const data = await readFile(filePath);
-      return new NextResponse(data, {
-        status: 200,
-        headers: { "Content-Type": mime, "Cache-Control": "public, max-age=3600" },
-      });
-    } catch {
-      return new NextResponse("Not found", { status: 404 });
-    }
-  };
-}

package/src/features/help/server/generateHelpArticleMetadata.ts

@@ -1,18 +0,0 @@
-import type { Metadata } from "next";
-import { findHelpArticle } from "../utils/helpNavigation";
-import { getHelpContent } from "./getHelpContent";
-
-export async function generateHelpArticleMetadata({
-  params,
-}: {
-  params: Promise<{ mode: string; slug: string }>;
-}): Promise<Metadata> {
-  const { mode, slug } = await params;
-  const article = findHelpArticle(getHelpContent().manifest, mode, slug);
-  if (!article) return {};
-  return {
-    title: article.title,
-    description: article.summary,
-    openGraph: { title: article.title, description: article.summary },
-  };
-}

package/src/features/help/server/generateHelpArticleStaticParams.ts

@@ -1,7 +0,0 @@
-import { getHelpContent } from "./getHelpContent";
-
-export function generateHelpArticleStaticParams(): { mode: string; slug: string }[] {
-  return getHelpContent()
-    .manifest.filter((a) => !a.draft)
-    .map((a) => ({ mode: a.mode, slug: a.slug }));
-}

package/src/features/help/server/generateHelpModeStaticParams.ts

@@ -1,5 +0,0 @@
-import { HELP_MODES } from "../types/help-article.types";
-
-export function generateHelpModeStaticParams(): { mode: string }[] {
-  return HELP_MODES.map((mode) => ({ mode }));
-}

package/src/features/help/server/getHelpContent.ts

@@ -1,17 +0,0 @@
-import { _getStaticHelpContent } from "../../../core/registry/helpStore";
-import type { HelpContentConfig } from "../interfaces/help-content-config.interface";
-
-/**
- * Server-side accessor for the help-content config set via configureJsonApi().
- * Returns the same value <HelpProvider> exposes via React Context to client components.
- * Throws with a setup error if helpContent was never configured.
- */
-export function getHelpContent(): HelpContentConfig {
-  const cfg = _getStaticHelpContent<HelpContentConfig>();
-  if (!cfg) {
-    throw new Error(
-      "Help content not configured — call configureJsonApi({ helpContent: {...} }) before importing help pages.",
-    );
-  }
-  return cfg;
-}

package/src/features/help/server/index.ts

@@ -1,8 +0,0 @@
-export { getHelpContent } from "./getHelpContent";
-export { renderHelpArticle, serializeHelpArticle } from "./serializeHelpArticle";
-export { generateHelpArticleStaticParams } from "./generateHelpArticleStaticParams";
-export { generateHelpArticleMetadata } from "./generateHelpArticleMetadata";
-export { generateHelpModeStaticParams } from "./generateHelpModeStaticParams";
-// NOTE: `createHelpAssetRouteHandler` is intentionally NOT re-exported here.
-// It uses `node:fs/promises` and must only be reachable via the dedicated
-// `@carlonicora/nextjs-jsonapi/help-asset-route` subpath, never the main bundle.

package/src/features/help/server/serializeHelpArticle.tsx

@@ -1,46 +0,0 @@
-import { MDXRemote } from "next-mdx-remote/rsc";
-import remarkGfm from "remark-gfm";
-import rehypeSlug from "rehype-slug";
-import rehypeAutolinkHeadings from "rehype-autolink-headings";
-import type { ReactElement } from "react";
-import type { HelpArticle } from "../types/help-article.types";
-import { _getStaticHelpReader } from "../../../core/registry/helpStore";
-import { MDX_SERVER_COMPONENTS } from "../components/mdx/mdx-server-components";
-
-/**
- * Server-side: read the article's raw markdown via the registered help reader
- * and render it through `next-mdx-remote/rsc`'s server-side MDXRemote, using
- * the server-safe MDX components (Callout, Steps, Screenshot, EntityRef,
- * KeyBinding, Video). The returned React element can be embedded inside a
- * server component (e.g. as `children` of `<HelpArticleBody>`).
- *
- * Note: `<Related>` is intentionally not part of the server map — it's a client
- * component that reads HelpContext. Articles that reference `<Related>` would
- * need a separate render path that injects the manifest by prop.
- */
-export async function renderHelpArticle(article: HelpArticle): Promise<ReactElement> {
-  const readRawMarkdown = _getStaticHelpReader();
-  if (!readRawMarkdown) {
-    throw new Error(
-      "Help reader not configured. Call setHelpReader(fn) from a server-only entrypoint (e.g. Next.js instrumentation register()) before rendering help articles.",
-    );
-  }
-  const source = await readRawMarkdown(article);
-  return (
-    <MDXRemote
-      source={source}
-      components={MDX_SERVER_COMPONENTS}
-      options={{
-        parseFrontmatter: true,
-        mdxOptions: {
-          remarkPlugins: [remarkGfm],
-          rehypePlugins: [rehypeSlug, [rehypeAutolinkHeadings, { behavior: "wrap" }]],
-        },
-      }}
-    />
-  );
-}
-
-/** @deprecated Use `renderHelpArticle` instead — the legacy serialize + client
- *  MDXRemote pattern is incompatible with App Router RSC. */
-export const serializeHelpArticle = renderHelpArticle;

package/src/features/help/utils/__tests__/helpNavigation.spec.ts

@@ -1,70 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { buildHelpNav, findHelpArticle, prevNextWithinMode } from "../helpNavigation";
-
-const base = {
-  tags: [],
-  contextualKeys: [],
-  aiIndexed: true,
-  draft: false,
-  contentHash: "h",
-  headings: [],
-  relatedSlugs: [],
-  lastUpdated: "",
-};
-const manifest = [
-  {
-    ...base,
-    id: "a",
-    slug: "a",
-    mode: "how-to" as const,
-    title: "Alpha",
-    summary: "s",
-    order: 1,
-    path: "how-to/a.mdx",
-  },
-  { ...base, id: "b", slug: "b", mode: "how-to" as const, title: "Beta", summary: "s", order: 2, path: "how-to/b.mdx" },
-  {
-    ...base,
-    id: "c",
-    slug: "c",
-    mode: "tutorial" as const,
-    title: "Gamma",
-    summary: "s",
-    order: 1,
-    path: "tutorial/c.mdx",
-  },
-];
-
-describe("helpNavigation", () => {
-  it("buildHelpNav groups articles by mode, sorted by order", () => {
-    const groups = buildHelpNav(manifest);
-    const howTo = groups.find((g) => g.mode === "how-to")!;
-    expect(howTo.articles.map((a) => a.slug)).toEqual(["a", "b"]);
-  });
-
-  it("findHelpArticle locates by mode + slug", () => {
-    expect(findHelpArticle(manifest, "how-to", "b")?.title).toBe("Beta");
-    expect(findHelpArticle(manifest, "how-to", "missing")).toBeUndefined();
-  });
-
-  it("prevNextWithinMode returns siblings within the same mode", () => {
-    const current = manifest[0]; // Alpha (how-to, order 1)
-    const { prev, next } = prevNextWithinMode(manifest, current);
-    expect(prev).toBeNull();
-    expect(next?.slug).toBe("b");
-  });
-
-  it("prevNextWithinMode returns null at the boundaries", () => {
-    const current = manifest[1]; // Beta (how-to, order 2)
-    const { prev, next } = prevNextWithinMode(manifest, current);
-    expect(prev?.slug).toBe("a");
-    expect(next).toBeNull();
-  });
-
-  it("prevNextWithinMode does not cross modes", () => {
-    const current = manifest[2]; // Gamma (tutorial)
-    const { prev, next } = prevNextWithinMode(manifest, current);
-    expect(prev).toBeNull();
-    expect(next).toBeNull();
-  });
-});

package/src/features/help/utils/helpNavigation.ts

@@ -1,29 +0,0 @@
-import { HELP_MODES, type HelpArticle, type HelpMode } from "../types/help-article.types";
-
-export interface HelpNavGroup {
-  mode: HelpMode;
-  articles: HelpArticle[];
-}
-
-export function buildHelpNav(manifest: readonly HelpArticle[]): HelpNavGroup[] {
-  return HELP_MODES.map((mode) => ({
-    mode,
-    articles: manifest.filter((a) => a.mode === mode && !a.draft).sort((a, b) => a.order - b.order),
-  }));
-}
-
-export function findHelpArticle(manifest: readonly HelpArticle[], mode: string, slug: string): HelpArticle | undefined {
-  return manifest.find((a) => a.mode === mode && a.slug === slug);
-}
-
-export function prevNextWithinMode(
-  manifest: readonly HelpArticle[],
-  current: HelpArticle,
-): { prev: HelpArticle | null; next: HelpArticle | null } {
-  const siblings = manifest.filter((a) => a.mode === current.mode && !a.draft).sort((a, b) => a.order - b.order);
-  const idx = siblings.findIndex((a) => a.slug === current.slug);
-  return {
-    prev: idx > 0 ? siblings[idx - 1] : null,
-    next: idx >= 0 && idx < siblings.length - 1 ? siblings[idx + 1] : null,
-  };
-}