@heyo-sh/create-heyo-docs 0.1.0

package/templates/next/app/components/docs-app.tsx

@@ -0,0 +1,139 @@
+"use client";
+
+import {
+  DocsApp,
+  openApiEndpointDataPath,
+  type OpenApiEndpoint,
+} from "@heyo-sh/heyo-docs";
+import {
+  createContext,
+  forwardRef,
+  useCallback,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+  type ComponentPropsWithoutRef,
+  type MouseEvent,
+} from "react";
+
+import { docsConfig, openApiEndpoints, pages } from "../_heyo-docs/content";
+import config from "../../heyo-docs.config";
+import { iconSet } from "../heyo-docs-icons";
+import { useTheme } from "./theme-provider";
+
+type Navigate = (href: string) => void;
+
+const NextNavigationContext = createContext<Navigate | undefined>(undefined);
+
+const NextDocsLink = forwardRef<
+  HTMLAnchorElement,
+  ComponentPropsWithoutRef<"a">
+>(function NextDocsLink({ href, onClick, target, ...props }, ref) {
+  const navigate = useContext(NextNavigationContext);
+
+  const handleClick = (event: MouseEvent<HTMLAnchorElement>) => {
+    onClick?.(event);
+    if (
+      !navigate ||
+      event.defaultPrevented ||
+      event.button !== 0 ||
+      event.metaKey ||
+      event.altKey ||
+      event.ctrlKey ||
+      event.shiftKey ||
+      target
+    )
+      return;
+
+    event.preventDefault();
+    navigate(href ?? "/");
+  };
+
+  return (
+    <a {...props} href={href} onClick={handleClick} ref={ref} target={target} />
+  );
+});
+
+export function NextDocsApp({
+  currentOpenApiEndpoint,
+  pathname,
+}: {
+  currentOpenApiEndpoint?: OpenApiEndpoint;
+  pathname: string;
+}) {
+  const { mounted, resolvedTheme, setTheme } = useTheme();
+  const [activePathname, setActivePathname] = useState(pathname);
+  const [activeOpenApiEndpoint, setActiveOpenApiEndpoint] = useState(
+    currentOpenApiEndpoint,
+  );
+  const navigationId = useRef(0);
+
+  const navigate = useCallback(async (href: string, updateHistory = true) => {
+    const destination = new URL(href, window.location.href);
+    if (destination.origin !== window.location.origin) {
+      window.location.assign(href);
+      return;
+    }
+
+    const nextPathname = destination.pathname;
+    const indexedEndpoint = openApiEndpoints.find(
+      (endpoint) => endpoint.slug === nextPathname,
+    );
+    const page = pages.find((candidate) => candidate.slug === nextPathname);
+    if (!indexedEndpoint && !page) {
+      window.location.assign(href);
+      return;
+    }
+
+    const currentNavigation = ++navigationId.current;
+    let endpoint: OpenApiEndpoint | undefined;
+    if (indexedEndpoint) {
+      const response = await fetch(
+        openApiEndpointDataPath(indexedEndpoint.slug),
+      );
+      if (!response.ok) {
+        window.location.assign(href);
+        return;
+      }
+      endpoint = (await response.json()) as OpenApiEndpoint;
+    }
+    if (currentNavigation !== navigationId.current) return;
+
+    if (updateHistory) window.history.pushState({}, "", destination);
+    document.title =
+      page?.seo.title ?? `${indexedEndpoint!.title} | ${docsConfig.title}`;
+    setActiveOpenApiEndpoint(endpoint);
+    setActivePathname(nextPathname);
+  }, []);
+
+  useEffect(() => {
+    const onPopState = () => {
+      void navigate(window.location.href, false);
+    };
+
+    window.addEventListener("popstate", onPopState);
+    return () => window.removeEventListener("popstate", onPopState);
+  }, [navigate]);
+
+  return (
+    <NextNavigationContext.Provider value={navigate}>
+      <DocsApp
+        config={{ ...docsConfig, navigation: config.navigation }}
+        iconSet={iconSet}
+        isDark={mounted ? resolvedTheme === "dark" : undefined}
+        link={NextDocsLink}
+        onThemeToggle={
+          mounted
+            ? () => setTheme(resolvedTheme === "dark" ? "light" : "dark")
+            : undefined
+        }
+        currentOpenApiEndpoint={activeOpenApiEndpoint}
+        openApiEndpoints={openApiEndpoints}
+        openApiRequestUrl="/heyo-docs-internal/openapi-request"
+        pages={pages}
+        pathname={activePathname}
+      />
+    </NextNavigationContext.Provider>
+  );
+}

package/templates/next/app/components/theme-provider.tsx

@@ -0,0 +1,93 @@
+"use client";
+
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useState,
+  type ReactNode,
+} from "react";
+
+import {
+  applyTheme,
+  DEFAULT_THEME,
+  getStoredTheme,
+  type ResolvedTheme,
+  THEME_STORAGE_KEY,
+  type Theme,
+} from "../lib/theme";
+
+type ThemeProviderState = {
+  theme: Theme;
+  resolvedTheme: ResolvedTheme;
+  mounted: boolean;
+  setTheme: (theme: Theme) => void;
+};
+
+const ThemeProviderContext = createContext<ThemeProviderState | undefined>(
+  undefined,
+);
+
+export function ThemeProvider({
+  children,
+  defaultTheme = DEFAULT_THEME,
+  storageKey = THEME_STORAGE_KEY,
+}: {
+  children: ReactNode;
+  defaultTheme?: Theme;
+  storageKey?: string;
+}) {
+  const [theme, setThemeState] = useState<Theme>(defaultTheme);
+  const [resolvedTheme, setResolvedTheme] = useState<ResolvedTheme>(
+    defaultTheme === "system" ? "light" : defaultTheme,
+  );
+  const [mounted, setMounted] = useState(false);
+
+  useEffect(() => {
+    const syncTheme = () => {
+      const nextTheme = getStoredTheme(storageKey, defaultTheme);
+      setThemeState(nextTheme);
+      setResolvedTheme(applyTheme(nextTheme));
+    };
+    syncTheme();
+    const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
+    const onSystemThemeChange = () => syncTheme();
+    const onStorage = (event: StorageEvent) => {
+      if (event.key === null || event.key === storageKey) syncTheme();
+    };
+    mediaQuery.addEventListener("change", onSystemThemeChange);
+    window.addEventListener("storage", onStorage);
+    setMounted(true);
+    return () => {
+      mediaQuery.removeEventListener("change", onSystemThemeChange);
+      window.removeEventListener("storage", onStorage);
+    };
+  }, [defaultTheme, storageKey]);
+
+  return (
+    <ThemeProviderContext.Provider
+      value={{
+        theme,
+        resolvedTheme,
+        mounted,
+        setTheme: (nextTheme) => {
+          try {
+            window.localStorage.setItem(storageKey, nextTheme);
+          } catch {
+            // The requested preference still applies when storage is unavailable.
+          }
+          setThemeState(nextTheme);
+          setResolvedTheme(applyTheme(nextTheme));
+        },
+      }}
+    >
+      {children}
+    </ThemeProviderContext.Provider>
+  );
+}
+
+export function useTheme() {
+  const context = useContext(ThemeProviderContext);
+  if (!context) throw new Error("useTheme must be used within a ThemeProvider");
+  return context;
+}

package/templates/next/app/error.tsx

@@ -0,0 +1,8 @@
+"use client";
+
+import { NextDocsApp } from "./components/docs-app";
+
+/** Retains the documentation chrome if an unexpected route error occurs. */
+export default function ErrorPage() {
+  return <NextDocsApp pathname="/__not-found" />;
+}

package/templates/next/app/heyo-docs-icons.tsx

@@ -0,0 +1,70 @@
+import {
+  RiArrowDownLine,
+  RiArrowDownSLine,
+  RiArrowRightLine,
+  RiArrowRightSLine,
+  RiArrowUpLine,
+  RiBookOpenLine,
+  RiChatAiLine,
+  RiCheckboxCircleLine,
+  RiCheckLine,
+  RiCloseCircleLine,
+  RiCloseLine,
+  RiCodeBoxLine,
+  RiCornerDownLeftLine,
+  RiCursorLine,
+  RiExternalLinkLine,
+  RiFileCopyLine,
+  RiFileTextLine,
+  RiFolderLine,
+  RiGitForkLine,
+  RiGitRepositoryLine,
+  RiGithubLine,
+  RiGlobalLine,
+  RiInformationLine,
+  RiLightbulbLine,
+  RiLoginBoxLine,
+  RiMenuLine,
+  RiMoonLine,
+  RiNewsLine,
+  RiSearchLine,
+  RiStarLine,
+  RiSunLine,
+} from "@remixicon/react";
+import type { IconSet } from "@heyo-sh/heyo-docs";
+
+/** Statically selected icons keep unused packs out of the client bundle. */
+export const iconSet = {
+  book: RiBookOpenLine,
+  changelog: RiNewsLine,
+  code: RiCodeBoxLine,
+  file: RiFileTextLine,
+  github: RiGithubLine,
+  globe: RiGlobalLine,
+  signIn: RiLoginBoxLine,
+  chevronDown: RiArrowDownSLine,
+  chevronRight: RiArrowRightSLine,
+  arrowDown: RiArrowDownLine,
+  arrowUp: RiArrowUpLine,
+  arrowRight: RiArrowRightLine,
+  close: RiCloseLine,
+  cornerDownLeft: RiCornerDownLeftLine,
+  menu: RiMenuLine,
+  search: RiSearchLine,
+  sun: RiSunLine,
+  moon: RiMoonLine,
+  checkCircle: RiCheckboxCircleLine,
+  check: RiCheckLine,
+  closeCircle: RiCloseCircleLine,
+  externalLink: RiExternalLinkLine,
+  folder: RiFolderLine,
+  gitFork: RiGitForkLine,
+  gitRepository: RiGitRepositoryLine,
+  information: RiInformationLine,
+  lightbulb: RiLightbulbLine,
+  copy: RiFileCopyLine,
+  star: RiStarLine,
+  bot: RiChatAiLine,
+  cursor: RiCursorLine,
+  chat: RiChatAiLine,
+} satisfies Required<IconSet>;

package/templates/next/app/heyo-docs-internal/markdown/[[...slug]]/route.ts

@@ -0,0 +1,26 @@
+import {
+  markdownForPage,
+  pathnameFromMarkdownPath,
+} from "@heyo-sh/heyo-docs/node";
+
+import { markdownPages } from "../../../lib/docs";
+
+/** Serves every documentation page as stable, frontmatter-free Markdown. */
+export async function GET(
+  _request: Request,
+  { params }: { params: Promise<{ slug?: string[] }> },
+) {
+  const { slug } = await params;
+  const pagePathname = pathnameFromMarkdownPath(`/${slug?.join("/") ?? ""}`);
+  const page = pagePathname
+    ? markdownPages.find((candidate) => candidate.slug === pagePathname)
+    : undefined;
+  if (!page)
+    return new Response("Not Found", {
+      status: 404,
+      headers: { "content-type": "text/plain; charset=utf-8" },
+    });
+  return new Response(markdownForPage(page), {
+    headers: { "content-type": "text/markdown; charset=utf-8" },
+  });
+}

package/templates/next/app/heyo-docs-internal/openapi-request/route.ts

@@ -0,0 +1,5 @@
+import { handleOpenApiRequest } from "../../lib/openapi-request";
+
+export async function POST(request: Request) {
+  return handleOpenApiRequest(request);
+}

package/templates/next/app/layout.tsx

@@ -0,0 +1,79 @@
+import type { Metadata } from "next";
+import type { ReactNode } from "react";
+
+import config from "../heyo-docs.config";
+import "./app.css";
+import { ThemeProvider } from "./components/theme-provider";
+import { getThemeScript, THEME_STORAGE_KEY } from "./lib/theme";
+
+export const metadata: Metadata = {
+  ...(config.siteUrl ? { metadataBase: new URL(config.siteUrl) } : {}),
+  title: config.title,
+  description: config.description,
+  robots: { index: true, follow: true },
+  alternates: {
+    ...(config.siteUrl ? { canonical: "/" } : {}),
+    ...(config.groups.some((group) => group.type === "changelog")
+      ? { types: { "application/rss+xml": "/rss.xml" } }
+      : {}),
+  },
+  manifest: "/site.webmanifest",
+  icons: {
+    icon: [
+      { url: "/favicon.ico", sizes: "any" },
+      { url: "/favicon.svg", type: "image/svg+xml" },
+      { url: "/favicon-96x96.png", sizes: "96x96", type: "image/png" },
+    ],
+    apple: [
+      { url: "/apple-touch-icon.png", sizes: "180x180", type: "image/png" },
+    ],
+  },
+  openGraph: {
+    type: "website",
+    siteName: config.title,
+    title: config.title,
+    description: config.description,
+    ...(config.siteUrl ? { url: config.siteUrl } : {}),
+  },
+  twitter: {
+    card: "summary",
+    title: config.title,
+    description: config.description,
+  },
+};
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <meta name="color-scheme" content="light dark" />
+        <meta name="referrer" content="strict-origin-when-cross-origin" />
+        <script
+          dangerouslySetInnerHTML={{
+            __html: getThemeScript(THEME_STORAGE_KEY, config.mode),
+          }}
+        />
+        <script
+          type="application/ld+json"
+          dangerouslySetInnerHTML={{
+            __html: JSON.stringify({
+              "@context": "https://schema.org",
+              "@type": "WebSite",
+              name: config.title,
+              description: config.description,
+              ...(config.siteUrl ? { url: config.siteUrl } : {}),
+            }).replace(/</g, "\\u003c"),
+          }}
+        />
+      </head>
+      <body>
+        <ThemeProvider
+          defaultTheme={config.mode}
+          storageKey={THEME_STORAGE_KEY}
+        >
+          {children}
+        </ThemeProvider>
+      </body>
+    </html>
+  );
+}

package/templates/next/app/lib/docs.ts

@@ -0,0 +1,43 @@
+import type { DocsPage } from "@heyo-sh/heyo-docs";
+import {
+  changelogGroupForPage,
+  createDocsModel,
+  findDocsPage,
+  findOpenApiEndpoint,
+  normaliseDocsPathname,
+} from "@heyo-sh/heyo-docs/node";
+
+import config from "../../heyo-docs.config";
+import {
+  docsPages,
+  markdownPages,
+  openApiDocuments,
+} from "../_heyo-docs/server";
+
+/** Server-only model: MDX components stay on the client-side module boundary. */
+export const docsModel = createDocsModel(
+  config,
+  docsPages as unknown as DocsPage[],
+  openApiDocuments,
+);
+
+export { config, markdownPages };
+
+export function pathnameForSegments(slug: string[] | undefined): string {
+  return normaliseDocsPathname(slug?.join("/") ?? "/");
+}
+
+export function docsContext(pathname: string) {
+  const page = findDocsPage(docsModel.pages, pathname);
+  const endpoint = findOpenApiEndpoint(docsModel.endpoints, pathname);
+  return {
+    config,
+    model: docsModel,
+    navigation: docsModel.navigation,
+    page,
+    endpoint,
+    changelogGroup: page
+      ? changelogGroupForPage(config.groups, page, docsModel.pages)
+      : undefined,
+  };
+}

package/templates/next/app/lib/openapi-request.ts

@@ -0,0 +1,147 @@
+import { findOpenApiEndpoint } from "@heyo-sh/heyo-docs/node";
+import type { OpenApiEndpoint } from "@heyo-sh/heyo-docs";
+
+import { docsModel } from "./docs";
+
+interface OpenApiRequestPayload {
+  bearerToken: string;
+  body?: string;
+  endpointSlug: string;
+  parameters: Record<string, string>;
+  server: string;
+}
+
+/** Sends documented API calls server-side after validating the declared server. */
+export async function handleOpenApiRequest(
+  request: Request,
+): Promise<Response> {
+  if (request.method !== "POST")
+    return new Response("Method Not Allowed", {
+      headers: { Allow: "POST" },
+      status: 405,
+    });
+  const payload = await requestPayload(request);
+  if (!payload)
+    return new Response("Invalid OpenAPI request.", { status: 400 });
+  const endpoint = findOpenApiEndpoint(
+    docsModel.endpoints,
+    payload.endpointSlug,
+  );
+  if (!endpoint) return new Response("Endpoint not found.", { status: 404 });
+  if (endpoint.servers.length && !endpoint.servers.includes(payload.server))
+    return new Response("API server is not declared in the OpenAPI schema.", {
+      status: 400,
+    });
+  if (!endpoint.servers.length && payload.server)
+    return new Response("This endpoint does not declare an API server.", {
+      status: 400,
+    });
+
+  try {
+    const response = await fetch(
+      requestUrl(endpoint, payload.server, payload.parameters, request.url),
+      {
+        method: endpoint.method.toUpperCase(),
+        headers: requestHeaders(
+          endpoint,
+          payload.parameters,
+          payload.bearerToken,
+        ),
+        body: payload.body,
+      },
+    );
+    const headers = new Headers();
+    const contentType = response.headers.get("content-type");
+    if (contentType) headers.set("content-type", contentType);
+    return new Response(
+      [204, 205, 304].includes(response.status)
+        ? null
+        : await response.arrayBuffer(),
+      { headers, status: response.status, statusText: response.statusText },
+    );
+  } catch {
+    return new Response("The API server could not be reached.", {
+      status: 502,
+    });
+  }
+}
+
+async function requestPayload(
+  request: Request,
+): Promise<OpenApiRequestPayload | undefined> {
+  try {
+    const value: unknown = await request.json();
+    if (!isRecord(value)) return undefined;
+    const endpointSlug = stringValue(value.endpointSlug);
+    const server = stringValue(value.server);
+    if (!endpointSlug || server === undefined) return undefined;
+    return {
+      endpointSlug,
+      server,
+      bearerToken: stringValue(value.bearerToken) ?? "",
+      body: stringValue(value.body),
+      parameters: stringRecord(value.parameters),
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+function requestUrl(
+  endpoint: OpenApiEndpoint,
+  server: string,
+  parameters: Record<string, string>,
+  requestUrl: string,
+) {
+  const path = endpoint.path.replace(
+    /\{([^}]+)\}/g,
+    (match: string, name: string) => {
+      const value = parameters[`path:${name}`];
+      return value ? encodeURIComponent(value) : match;
+    },
+  );
+  const query = new URLSearchParams();
+  for (const parameter of endpoint.parameters) {
+    if (parameter.in !== "query") continue;
+    const value = parameters[`query:${parameter.name}`];
+    if (value) query.set(parameter.name, value);
+  }
+  const destination = `${path}${query.size ? `?${query}` : ""}`;
+  return server
+    ? `${server.replace(/\/$/, "")}${destination}`
+    : new URL(destination, requestUrl).toString();
+}
+
+function requestHeaders(
+  endpoint: OpenApiEndpoint,
+  parameters: Record<string, string>,
+  bearerToken: string,
+) {
+  const headers = new Headers();
+  for (const parameter of endpoint.parameters) {
+    if (parameter.in !== "header") continue;
+    const value = parameters[`header:${parameter.name}`];
+    if (value) headers.set(parameter.name, value);
+  }
+  if (endpoint.requestBody?.contentType)
+    headers.set("Content-Type", endpoint.requestBody.contentType);
+  if (bearerToken) headers.set("Authorization", `Bearer ${bearerToken}`);
+  return headers;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function stringRecord(value: unknown): Record<string, string> {
+  if (!isRecord(value)) return {};
+  return Object.fromEntries(
+    Object.entries(value).filter(
+      (entry): entry is [string, string] => typeof entry[1] === "string",
+    ),
+  );
+}
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}