radiant-docs 0.1.58 → 0.1.60

package/template/src/lib/font-css.ts

@@ -0,0 +1,376 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { resolveStaticAssetUrl } from "./static-asset-url";
+import {
+  DEFAULT_CODE_FONT_PRESET,
+  DEFAULT_TEXT_FONT_PRESET,
+  FONT_PRESET_OPTIONS,
+  type DocsConfig,
+  type FontPresetOption,
+} from "./validation";
+
+const require = createRequire(import.meta.url);
+
+const FONT_ROUTE_PREFIX = "/-/fonts";
+const FONT_CONTENT_TYPE = "font/woff2";
+const FONT_DISPLAY = "block";
+
+type FontPresetId = FontPresetOption;
+
+type FontSourceFile = {
+  fileName: string;
+  preload?: boolean;
+};
+
+type FontsourceConfig = {
+  packageName: string;
+  routeDir: string;
+  cssFiles: string[];
+  files: FontSourceFile[];
+};
+
+type FontPreset = {
+  stack: string;
+  fontsource?: FontsourceConfig;
+};
+
+export type FontPreload = {
+  href: string;
+  type: "font/woff2";
+};
+
+export type DocsFontFile = {
+  routePath: string;
+  sourcePath: string;
+  contentType: typeof FONT_CONTENT_TYPE;
+};
+
+const fontCssCache = new Map<FontPresetId, string>();
+const fontRoutePathCache = new Map<string, string>();
+
+const LATIN_UNICODE_FILES = ["latin-ext", "latin"] as const;
+const FONT_STYLES = ["normal", "italic"] as const;
+
+function getFontsourceFiles(fontId: string): FontSourceFile[] {
+  return FONT_STYLES.flatMap((style) =>
+    LATIN_UNICODE_FILES.map((subset) => ({
+      fileName: `${fontId}-${subset}-wght-${style}.woff2`,
+      preload: subset === "latin" && style === "normal",
+    })),
+  );
+}
+
+const FONT_PRESETS: Record<FontPresetId, FontPreset> = {
+  "google-sans": {
+    stack: '"Google Sans Variable", ui-sans-serif, system-ui, sans-serif',
+    fontsource: {
+      packageName: "@fontsource-variable/google-sans",
+      routeDir: "google-sans",
+      cssFiles: ["wght.css", "wght-italic.css"],
+      files: getFontsourceFiles("google-sans"),
+    },
+  },
+  inter: {
+    stack: '"Inter Variable", ui-sans-serif, system-ui, sans-serif',
+    fontsource: {
+      packageName: "@fontsource-variable/inter",
+      routeDir: "inter",
+      cssFiles: ["wght.css", "wght-italic.css"],
+      files: getFontsourceFiles("inter"),
+    },
+  },
+  "inter-tight": {
+    stack: '"Inter Tight Variable", ui-sans-serif, system-ui, sans-serif',
+    fontsource: {
+      packageName: "@fontsource-variable/inter-tight",
+      routeDir: "inter-tight",
+      cssFiles: ["wght.css", "wght-italic.css"],
+      files: getFontsourceFiles("inter-tight"),
+    },
+  },
+  geist: {
+    stack: '"Geist Variable", ui-sans-serif, system-ui, sans-serif',
+    fontsource: {
+      packageName: "@fontsource-variable/geist",
+      routeDir: "geist",
+      cssFiles: ["wght.css", "wght-italic.css"],
+      files: getFontsourceFiles("geist"),
+    },
+  },
+  "source-sans-3": {
+    stack: '"Source Sans 3 Variable", ui-sans-serif, system-ui, sans-serif',
+    fontsource: {
+      packageName: "@fontsource-variable/source-sans-3",
+      routeDir: "source-sans-3",
+      cssFiles: ["wght.css", "wght-italic.css"],
+      files: getFontsourceFiles("source-sans-3"),
+    },
+  },
+  "source-serif-4": {
+    stack:
+      '"Source Serif 4 Variable", ui-serif, Georgia, Cambria, "Times New Roman", Times, serif',
+    fontsource: {
+      packageName: "@fontsource-variable/source-serif-4",
+      routeDir: "source-serif-4",
+      cssFiles: ["wght.css", "wght-italic.css"],
+      files: getFontsourceFiles("source-serif-4"),
+    },
+  },
+  "public-sans": {
+    stack: '"Public Sans Variable", ui-sans-serif, system-ui, sans-serif',
+    fontsource: {
+      packageName: "@fontsource-variable/public-sans",
+      routeDir: "public-sans",
+      cssFiles: ["wght.css", "wght-italic.css"],
+      files: getFontsourceFiles("public-sans"),
+    },
+  },
+  "geist-mono": {
+    stack:
+      '"Geist Mono Variable", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace',
+    fontsource: {
+      packageName: "@fontsource-variable/geist-mono",
+      routeDir: "geist-mono",
+      cssFiles: ["wght.css", "wght-italic.css"],
+      files: getFontsourceFiles("geist-mono"),
+    },
+  },
+  "jetbrains-mono": {
+    stack:
+      '"JetBrains Mono Variable", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace',
+    fontsource: {
+      packageName: "@fontsource-variable/jetbrains-mono",
+      routeDir: "jetbrains-mono",
+      cssFiles: ["wght.css", "wght-italic.css"],
+      files: getFontsourceFiles("jetbrains-mono"),
+    },
+  },
+  "google-sans-code": {
+    stack:
+      '"Google Sans Code Variable", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace',
+    fontsource: {
+      packageName: "@fontsource-variable/google-sans-code",
+      routeDir: "google-sans-code",
+      cssFiles: ["wght.css", "wght-italic.css"],
+      files: getFontsourceFiles("google-sans-code"),
+    },
+  },
+  "system-sans": {
+    stack: 'ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif',
+  },
+  "system-serif": {
+    stack: 'ui-serif, Georgia, Cambria, "Times New Roman", Times, serif',
+  },
+  "system-mono": {
+    stack:
+      'ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace',
+  },
+};
+
+type FontThemeConfig = {
+  text?: unknown;
+  heading?: unknown;
+  code?: unknown;
+};
+
+const FONT_PRESET_ID_SET = new Set<FontPresetId>(FONT_PRESET_OPTIONS);
+
+function getConfiguredFonts(theme: DocsConfig["theme"]): FontThemeConfig {
+  return theme?.fonts ?? {};
+}
+
+function normalizeFontPresetId(value: unknown): FontPresetId | null {
+  if (typeof value !== "string") return null;
+
+  const normalized = value.trim().toLowerCase();
+  return FONT_PRESET_ID_SET.has(normalized as FontPresetId)
+    ? (normalized as FontPresetId)
+    : null;
+}
+
+function resolveFontPresetIds(theme: DocsConfig["theme"]): {
+  text: FontPresetId;
+  heading: FontPresetId;
+  code: FontPresetId;
+} {
+  const fonts = getConfiguredFonts(theme);
+  const text = normalizeFontPresetId(fonts.text) ?? DEFAULT_TEXT_FONT_PRESET;
+  return {
+    text,
+    heading: normalizeFontPresetId(fonts.heading) ?? text,
+    code: normalizeFontPresetId(fonts.code) ?? DEFAULT_CODE_FONT_PRESET,
+  };
+}
+
+function getFontsourceCssPath(
+  fontsource: FontsourceConfig,
+  cssFile: string,
+): string {
+  return require.resolve(`${fontsource.packageName}/${cssFile}`);
+}
+
+function getFontsourceFilePath(
+  fontsource: FontsourceConfig,
+  fileName: string,
+): string {
+  return require.resolve(`${fontsource.packageName}/files/${fileName}`);
+}
+
+function getFontsourceCssUrlPattern(): RegExp {
+  return /url\((["']?)\.\/files\/([^"')]+)\1\)/g;
+}
+
+function getFontFaceBlockPattern(): RegExp {
+  return /(?:\/\*[\s\S]*?\*\/\s*)?@font-face\s*\{[\s\S]*?\}\s*/g;
+}
+
+function applyFontDisplay(block: string): string {
+  return block.replace(/font-display:\s*[^;]+;/, `font-display: ${FONT_DISPLAY};`);
+}
+
+function getFontRoutePath(
+  fontsource: FontsourceConfig,
+  fileName: string,
+): string {
+  const cacheKey = `${fontsource.packageName}/${fileName}`;
+  const cachedRoutePath = fontRoutePathCache.get(cacheKey);
+  if (cachedRoutePath) return cachedRoutePath;
+
+  const sourcePath = getFontsourceFilePath(fontsource, fileName);
+  const hash = crypto
+    .createHash("sha256")
+    .update(fs.readFileSync(sourcePath))
+    .digest("hex")
+    .slice(0, 12);
+  const extension = path.extname(fileName);
+  const basename = path.basename(fileName, extension);
+  const routePath = `${fontsource.routeDir}/${basename}.${hash}${extension}`;
+
+  fontRoutePathCache.set(cacheKey, routePath);
+  return routePath;
+}
+
+function getFontPublicUrl(
+  fontsource: FontsourceConfig,
+  fileName: string,
+): string {
+  return resolveStaticAssetUrl(
+    `${FONT_ROUTE_PREFIX}/${getFontRoutePath(fontsource, fileName)}`,
+  );
+}
+
+function getFontsourceCss(presetId: FontPresetId): string {
+  const cachedCss = fontCssCache.get(presetId);
+  if (cachedCss !== undefined) return cachedCss;
+
+  const fontsource = FONT_PRESETS[presetId].fontsource;
+  if (!fontsource) return "";
+
+  const includedFiles = new Set(
+    fontsource.files.map((fontFile) => fontFile.fileName),
+  );
+  const matchedFiles = new Set<string>();
+  const resolvedCss = fontsource.cssFiles
+    .flatMap((cssFile) => {
+      const css = fs.readFileSync(getFontsourceCssPath(fontsource, cssFile), {
+        encoding: "utf8",
+      });
+
+      return Array.from(css.matchAll(getFontFaceBlockPattern()), ([block]) => {
+        const urlMatch = getFontsourceCssUrlPattern().exec(block);
+        const fileName = urlMatch?.[2];
+        if (!fileName || !includedFiles.has(fileName)) return "";
+
+        matchedFiles.add(fileName);
+        return applyFontDisplay(block).replace(
+          getFontsourceCssUrlPattern(),
+          (_match, _quote, matchedFileName) =>
+            `url("${getFontPublicUrl(fontsource, matchedFileName)}")`,
+        );
+      });
+    })
+    .filter(Boolean)
+    .join("\n");
+
+  const missingFiles = Array.from(includedFiles).filter(
+    (fileName) => !matchedFiles.has(fileName),
+  );
+  if (missingFiles.length > 0) {
+    throw new Error(
+      `Font preset "${presetId}" is missing @font-face blocks for: ${missingFiles.join(
+        ", ",
+      )}.`,
+    );
+  }
+
+  fontCssCache.set(presetId, resolvedCss);
+  return resolvedCss;
+}
+
+function getSelectedFontPresetIds(theme: DocsConfig["theme"]): FontPresetId[] {
+  const fontPresetIds = resolveFontPresetIds(theme);
+  return [...new Set(Object.values(fontPresetIds))];
+}
+
+export function getDocsFontCss(theme: DocsConfig["theme"]): string {
+  const fontPresetIds = resolveFontPresetIds(theme);
+  const fontFaceCss = getSelectedFontPresetIds(theme).map((presetId) =>
+    getFontsourceCss(presetId),
+  );
+
+  return [
+    ...fontFaceCss.filter(Boolean),
+    ":root {",
+    `  --rd-font-text: ${FONT_PRESETS[fontPresetIds.text].stack};`,
+    `  --rd-font-heading: ${FONT_PRESETS[fontPresetIds.heading].stack};`,
+    `  --rd-font-code: ${FONT_PRESETS[fontPresetIds.code].stack};`,
+    "}",
+  ].join("\n");
+}
+
+export function getDocsFontPreloads(
+  theme: DocsConfig["theme"],
+): FontPreload[] {
+  const preloadUrls = new Set<string>();
+
+  for (const presetId of getSelectedFontPresetIds(theme)) {
+    const fontsource = FONT_PRESETS[presetId].fontsource;
+    if (!fontsource) continue;
+
+    for (const fontFile of fontsource.files) {
+      if (!fontFile.preload) continue;
+      preloadUrls.add(getFontPublicUrl(fontsource, fontFile.fileName));
+    }
+  }
+
+  return Array.from(preloadUrls, (href) => ({
+    href,
+    type: "font/woff2" as const,
+  }));
+}
+
+export function getSelectedDocsFontFiles(
+  theme: DocsConfig["theme"],
+): DocsFontFile[] {
+  const fontFiles = new Map<string, DocsFontFile>();
+
+  for (const presetId of getSelectedFontPresetIds(theme)) {
+    const fontsource = FONT_PRESETS[presetId].fontsource;
+    if (!fontsource) continue;
+
+    for (const fontFile of fontsource.files) {
+      const routePath = getFontRoutePath(fontsource, fontFile.fileName);
+      fontFiles.set(routePath, {
+        routePath,
+        sourcePath: getFontsourceFilePath(fontsource, fontFile.fileName),
+        contentType: FONT_CONTENT_TYPE,
+      });
+    }
+  }
+
+  return Array.from(fontFiles.values()).sort((a, b) =>
+    a.routePath.localeCompare(b.routePath),
+  );
+}

package/template/src/lib/mdx/remark-resolve-internal-links.ts

@@ -8,7 +8,6 @@ import {
   loadOpenApiSpec,
   resolveDocsHref,
   type DocsConfig,
-  type HiddenPageRoute,
   type NavGroup,
   type NavMenuItem,
   type NavOpenApi,
@@ -28,6 +27,15 @@ import {
 
 type MdxNavItem = string | NavPage | NavGroup | NavOpenApiPage;
 
+type AuxiliaryPageRef = {
+  filePath: string;
+  href: string;
+};
+
+type DocsConfigWithAuxiliaryRefs = DocsConfig & {
+  auxiliaryPageRefs?: AuxiliaryPageRef[];
+};
+
 type ResolvedRouteIndex = {
   canonicalHrefByFilePath: Map<string, string>;
   allHrefsByFilePath: Map<string, string[]>;
@@ -230,14 +238,14 @@ function addOpenApiEndpointRoute(args: {
   );
 }
 
-function addHiddenPageRoute(
+function addAuxiliaryPageRef(
   index: ResolvedRouteIndex,
-  route: HiddenPageRoute,
+  ref: AuxiliaryPageRef,
 ): void {
-  const normalizedFilePath = normalizeDocsFilePath(route.filePath);
+  const normalizedFilePath = normalizeDocsFilePath(ref.filePath);
   if (!normalizedFilePath) return;
 
-  const href = addValidRoutePath(index, prependBasePath(route.href));
+  const href = addValidRoutePath(index, prependBasePath(ref.href));
   if (!index.canonicalHrefByFilePath.has(normalizedFilePath)) {
     index.canonicalHrefByFilePath.set(normalizedFilePath, href);
   }
@@ -249,6 +257,12 @@ function addHiddenPageRoute(
   index.allHrefsByFilePath.set(normalizedFilePath, aliases);
 }
 
+function getAuxiliaryPageRefs(
+  config: DocsConfigWithAuxiliaryRefs,
+): AuxiliaryPageRef[] {
+  return config.auxiliaryPageRefs ?? [];
+}
+
 function shouldIncludeEndpoint(
   method: string,
   pathStr: string,
@@ -474,14 +488,14 @@ async function buildRouteIndex(
   }
 
   if (homePath) {
-    addHiddenPageRoute(index, {
+    addAuxiliaryPageRef(index, {
       filePath: homePath,
       href: "/",
     });
   }
 
-  for (const hiddenPageRoute of config.hiddenPageRoutes ?? []) {
-    addHiddenPageRoute(index, hiddenPageRoute);
+  for (const auxiliaryPageRef of getAuxiliaryPageRefs(config)) {
+    addAuxiliaryPageRef(index, auxiliaryPageRef);
   }
 
   return index;

package/template/src/lib/oas.ts

@@ -4,6 +4,10 @@ import { loadOpenApiSpec } from "./validation";
 // Cache for dereferenced Oas instances (key: filePathOrUrl, value: Oas instance)
 const oasInstanceCache = new Map<string, Oas>();
 
+function cloneOpenApiDocument<T>(document: T): T {
+  return JSON.parse(JSON.stringify(document));
+}
+
 export async function getOasInstance(filePathOrUrl: string): Promise<Oas> {
   // Check cache first
   if (oasInstanceCache.has(filePathOrUrl)) {
@@ -14,7 +18,7 @@ export async function getOasInstance(filePathOrUrl: string): Promise<Oas> {
   const openApiDoc = await loadOpenApiSpec(filePathOrUrl);
 
   // Create and dereference Oas instance
-  const api = new Oas(openApiDoc);
+  const api = new Oas(cloneOpenApiDocument(openApiDoc));
   await api.dereference();
 
   // Cache the dereferenced instance