@heyo-sh/create-heyo-docs 0.1.0

package/templates/astro/src/components/docs-app.tsx

@@ -0,0 +1,165 @@
+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 config from "../../heyo-docs.config";
+import { iconSet } from "../heyo-docs-icons";
+import { THEME_STORAGE_KEY } from "../lib/theme";
+import { openApiEndpoints } from "virtual:heyo-docs-openapi/index";
+import { pages } from "virtual:heyo-docs-content";
+import { ThemeProvider, useTheme } from "./theme-provider";
+
+type Navigate = (href: string) => void;
+
+const AstroNavigationContext = createContext<Navigate | undefined>(undefined);
+
+const AstroLink = forwardRef<HTMLAnchorElement, ComponentPropsWithoutRef<"a">>(
+  function AstroLink({ href, onClick, target, ...props }, ref) {
+    const navigate = useContext(AstroNavigationContext);
+
+    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 AstroDocsApp({
+  currentOpenApiEndpoint,
+  pathname,
+}: {
+  currentOpenApiEndpoint?: OpenApiEndpoint;
+  pathname: string;
+}) {
+  return (
+    <ThemeProvider defaultTheme={config.mode} storageKey={THEME_STORAGE_KEY}>
+      <DocsShell
+        currentOpenApiEndpoint={currentOpenApiEndpoint}
+        pathname={pathname}
+      />
+    </ThemeProvider>
+  );
+}
+
+/**
+ * Content is imported in this island instead of crossing Astro's serialisation
+ * boundary. MDX pages are React components and must stay module references.
+ */
+function DocsShell({
+  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} | ${config.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 (
+    <AstroNavigationContext.Provider value={navigate}>
+      <DocsApp
+        config={config}
+        iconSet={iconSet}
+        isDark={mounted ? resolvedTheme === "dark" : undefined}
+        link={AstroLink}
+        onThemeToggle={
+          mounted
+            ? () => setTheme(resolvedTheme === "dark" ? "light" : "dark")
+            : undefined
+        }
+        currentOpenApiEndpoint={activeOpenApiEndpoint}
+        openApiEndpoints={openApiEndpoints}
+        openApiRequestUrl="/heyo-docs-internal/openapi-request"
+        pages={pages}
+        pathname={activePathname}
+      />
+    </AstroNavigationContext.Provider>
+  );
+}

package/templates/astro/src/components/theme-provider.tsx

@@ -0,0 +1,106 @@
+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 ThemeProviderProps = {
+  children: ReactNode;
+  defaultTheme?: Theme;
+  storageKey?: string;
+};
+
+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,
+}: ThemeProviderProps) {
+  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 handleSystemThemeChange = () => {
+      const nextTheme = getStoredTheme(storageKey, defaultTheme);
+      setResolvedTheme(applyTheme(nextTheme));
+    };
+    const handleStorage = (event: StorageEvent) => {
+      if (event.key !== null && event.key !== storageKey) return;
+      syncTheme();
+    };
+
+    mediaQuery.addEventListener("change", handleSystemThemeChange);
+    window.addEventListener("storage", handleStorage);
+    setMounted(true);
+
+    return () => {
+      mediaQuery.removeEventListener("change", handleSystemThemeChange);
+      window.removeEventListener("storage", handleStorage);
+    };
+  }, [defaultTheme, storageKey]);
+
+  const value = {
+    theme,
+    resolvedTheme,
+    mounted,
+    setTheme: (nextTheme: Theme) => {
+      try {
+        window.localStorage.setItem(storageKey, nextTheme);
+      } catch {
+        // The requested preference still applies when storage is unavailable.
+      }
+
+      setThemeState(nextTheme);
+      setResolvedTheme(applyTheme(nextTheme));
+    },
+  };
+
+  return (
+    <ThemeProviderContext.Provider value={value}>
+      {children}
+    </ThemeProviderContext.Provider>
+  );
+}
+
+export function useTheme() {
+  const context = useContext(ThemeProviderContext);
+
+  if (context === undefined)
+    throw new Error("useTheme must be used within a ThemeProvider");
+
+  return context;
+}

package/templates/astro/src/env.d.ts

@@ -0,0 +1,2 @@
+/// <reference path="../.astro/types.d.ts" />
+/// <reference types="astro/client" />

package/templates/astro/src/heyo-docs-icons.tsx

@@ -0,0 +1,79 @@
+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,
+  RiMoonLine,
+  RiNewsLine,
+  RiSearchLine,
+  RiStarLine,
+  RiSunLine,
+} from "@remixicon/react";
+import type { IconSet } from "@heyo-sh/heyo-docs";
+
+/**
+ * This mapping is intentionally local to the generated application. Replace
+ * it with another pack to change the built-in UI without bundling all packs.
+ */
+const remixIconSet = {
+  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,
+  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,
+};
+
+/**
+ * A generated project can temporarily resolve the icon package and Heyo Docs
+ * through distinct React type installations (notably with file dependencies).
+ * The runtime contract is identical SVG props, so expose the local mapping as
+ * the framework-neutral icon contract after keeping the imports tree-shakeable.
+ */
+export const iconSet = remixIconSet as unknown as Required<IconSet>;

package/templates/astro/src/layouts/docs-layout.astro

@@ -0,0 +1,70 @@
+---
+import config from "../../heyo-docs.config";
+import "../styles/app.css";
+import { getThemeScript, THEME_STORAGE_KEY } from "../lib/theme";
+
+interface Props {
+  title: string;
+  description: string;
+  canonical?: string;
+  robots?: "index, follow" | "noindex";
+  structuredData: unknown[];
+}
+
+const {
+  title,
+  description,
+  canonical,
+  robots = "index, follow",
+  structuredData,
+} = Astro.props;
+const jsonLd = JSON.stringify(structuredData).replace(/</g, "\\u003c");
+const hasChangelog = config.groups.some((group) => group.type === "changelog");
+---
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="color-scheme" content="light dark" />
+    <meta name="robots" content={robots} />
+    <meta name="referrer" content="strict-origin-when-cross-origin" />
+    <title>{title}</title>
+    <meta name="description" content={description} />
+    <meta property="og:type" content="article" />
+    <meta property="og:site_name" content={config.title} />
+    <meta property="og:title" content={title} />
+    <meta property="og:description" content={description} />
+    <meta name="twitter:card" content="summary" />
+    <meta name="twitter:title" content={title} />
+    <meta name="twitter:description" content={description} />
+    {canonical && <link rel="canonical" href={canonical} />}
+    {canonical && <meta property="og:url" content={canonical} />}
+    <link rel="icon" href="/favicon.ico" sizes="any" />
+    <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
+    <link
+      rel="icon"
+      href="/favicon-96x96.png"
+      sizes="96x96"
+      type="image/png"
+    />
+    <link rel="apple-touch-icon" href="/apple-touch-icon.png" sizes="180x180" />
+    <link rel="manifest" href="/site.webmanifest" />
+    {
+      hasChangelog && (
+        <link
+          rel="alternate"
+          href="/rss.xml"
+          type="application/rss+xml"
+          title={`${config.title} updates`}
+        />
+      )
+    }
+    <script is:inline set:html={getThemeScript(THEME_STORAGE_KEY, config.mode)}></script>
+    <script is:inline type="application/ld+json" set:html={jsonLd}></script>
+  </head>
+  <body>
+    <slot />
+  </body>
+</html>

package/templates/astro/src/lib/docs.ts

@@ -0,0 +1,31 @@
+import {
+  changelogGroupForPage,
+  createDocsModel,
+  findDocsPage,
+  findOpenApiEndpoint,
+  normaliseDocsPathname,
+} from "@heyo-sh/heyo-docs";
+
+import config from "../../heyo-docs.config";
+import { openApiDocuments } from "virtual:heyo-docs-openapi";
+import { pages } from "virtual:heyo-docs-content";
+
+export function pathnameForSlug(slug: string | undefined): string {
+  return normaliseDocsPathname(slug ? `/${slug}` : "/");
+}
+
+export function docsContext(pathname: string) {
+  const model = createDocsModel(config, pages, openApiDocuments);
+  const page = findDocsPage(model.pages, pathname);
+  const endpoint = findOpenApiEndpoint(model.endpoints, pathname);
+
+  return {
+    config,
+    model,
+    page,
+    endpoint,
+    changelogGroup: page
+      ? changelogGroupForPage(config.groups, page, model.pages)
+      : undefined,
+  };
+}

package/templates/astro/src/lib/openapi-request.ts

@@ -0,0 +1,160 @@
+import {
+  createDocsModel,
+  findOpenApiEndpoint,
+  type OpenApiEndpoint,
+} from "@heyo-sh/heyo-docs";
+
+import config from "../../heyo-docs.config";
+import { openApiDocuments } from "virtual:heyo-docs-openapi";
+import { pages } from "virtual:heyo-docs-content";
+
+interface OpenApiRequestPayload {
+  bearerToken: string;
+  body?: string;
+  endpointSlug: string;
+  parameters: Record<string, string>;
+  server: string;
+}
+
+/**
+ * Sends documented API calls from the server, so browsers do not need the API
+ * to expose CORS headers. Targets are limited to servers from the OpenAPI file.
+ */
+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 model = createDocsModel(config, pages, openApiDocuments);
+  const endpoint = findOpenApiEndpoint(model.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,
+    });
+
+  const headers = requestHeaders(
+    endpoint,
+    payload.parameters,
+    payload.bearerToken,
+  );
+  const url = requestUrl(
+    endpoint,
+    payload.server,
+    payload.parameters,
+    request.url,
+  );
+
+  try {
+    const response = await fetch(url, {
+      method: endpoint.method.toUpperCase(),
+      headers,
+      body: payload.body,
+    });
+    const responseHeaders = new Headers();
+    const contentType = response.headers.get("content-type");
+    if (contentType) responseHeaders.set("content-type", contentType);
+    const body = [204, 205, 304].includes(response.status)
+      ? null
+      : await response.arrayBuffer();
+    return new Response(body, {
+      headers: responseHeaders,
+      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 {
+      bearerToken: stringValue(value.bearerToken) ?? "",
+      body: stringValue(value.body),
+      endpointSlug,
+      parameters: stringRecord(value.parameters),
+      server,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+function requestUrl(
+  endpoint: OpenApiEndpoint,
+  server: string,
+  parameters: Record<string, string>,
+  requestUrl: string,
+) {
+  let path = endpoint.path.replace(/\{([^}]+)\}/g, (match, 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 search = query.toString();
+  path = `${path}${search ? `?${search}` : ""}`;
+  return server
+    ? `${server.replace(/\/$/, "")}${path}`
+    : new URL(path, 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;
+}