radiant-docs 0.1.39 → 0.1.41

package/template/src/lib/routes.ts

@@ -5,6 +5,7 @@ import {
   type NavOpenApiPage,
   type NavMenuItem,
   type NavOpenApi,
+  type HiddenPageRoute,
   loadOpenApiSpec,
 } from "./validation";
 import {
@@ -21,6 +22,7 @@ type MdxNavPageItem = string | NavPage;
 export interface BaseRoute {
   slug: string;
   title: string;
+  hidden?: boolean;
 }
 
 // MDX route
@@ -95,6 +97,35 @@ function processPageItem(
   };
 }
 
+function processHiddenPageRoute(
+  route: HiddenPageRoute,
+  docs: any[],
+): MdxRoute {
+  const entry = docs.find((doc: any) => {
+    const docPath = doc.id.replace(/\.mdx$/, "");
+    return docPath === route.filePath;
+  });
+
+  if (!entry) {
+    throw new Error(
+      `Could not find content collection entry for path: ${route.filePath}`,
+    );
+  }
+
+  const slug = route.href.replace(/^\/+/, "").replace(/\/+$/, "");
+
+  return {
+    type: "mdx",
+    slug,
+    filePath: route.filePath,
+    title: resolveMdxPageTitle({
+      entry,
+      filePath: route.filePath,
+    }),
+    hidden: true,
+  };
+}
+
 type OpenApiOperationLookup = {
   method: string;
   path: string;
@@ -368,7 +399,7 @@ function assertUniqueRouteSlugs(routes: Route[]): void {
         : `openapi:${route.filePath}:${route.openApiMethod.toUpperCase()} ${route.openApiPath}`;
 
     throw new Error(
-      `Duplicate route slug "${route.slug}" generated by "${existingLabel}" and "${candidateLabel}".`,
+      `[USER_ERROR]: Invalid docs.json: Duplicate route slug "${route.slug}" generated by "${existingLabel}" and "${candidateLabel}". Remove one of the duplicate references or change navigation structure so each route resolves to a unique URL.`,
     );
   }
 }
@@ -405,6 +436,23 @@ export async function getAllRoutes(): Promise<Route[]> {
     }
   }
 
+  for (const hiddenPageRoute of config.hiddenPageRoutes ?? []) {
+    const hiddenRoute = processHiddenPageRoute(hiddenPageRoute, docs);
+    const existingRoute = allRoutes.find(
+      (route) => route.slug === hiddenRoute.slug,
+    );
+    if (existingRoute) {
+      if (
+        existingRoute.type === "mdx" &&
+        existingRoute.filePath === hiddenRoute.filePath
+      ) {
+        continue;
+      }
+    }
+
+    allRoutes.push(hiddenRoute);
+  }
+
   assertUniqueRouteSlugs(allRoutes);
   return allRoutes;
 }

package/template/src/lib/static-asset-url.ts

@@ -1,3 +1,5 @@
+import { withBasePath } from "./base-path";
+
 type AssetsPrefixValue = string | Record<string, string> | undefined;
 
 function normalizePrefix(value: string): string {
@@ -54,7 +56,7 @@ export function resolveStaticAssetUrl(rawPath: string): string {
 
   const prefix = resolveAssetsPrefix(import.meta.env.ASSETS_PREFIX);
   if (!prefix) {
-    return `${normalizedPathname}${parsed.search}${parsed.hash}`;
+    return `${withBasePath(normalizedPathname)}${parsed.search}${parsed.hash}`;
   }
 
   const normalizedPrefixPath = `${prefix}/${normalizedPathname.replace(/^\/+/, "")}`;

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

@@ -0,0 +1,176 @@
+import colors from "tailwindcss/colors";
+import {
+  DEFAULT_THEME_COLOR_DARK,
+  DEFAULT_THEME_COLOR_LIGHT,
+  type BaseColorOption,
+  type DocsConfig,
+} from "./validation";
+
+const neutralColorShades = [
+  "50",
+  "100",
+  "200",
+  "300",
+  "400",
+  "500",
+  "600",
+  "700",
+  "800",
+  "900",
+  "950",
+] as const;
+type NeutralColorShade = (typeof neutralColorShades)[number];
+
+const paletteColors = colors as unknown as Record<
+  string,
+  Record<NeutralColorShade, string>
+>;
+
+function normalizeHexColorToRgb(
+  hexColor: string,
+): { r: number; g: number; b: number } | null {
+  const normalized = hexColor.replace("#", "").trim();
+  if (/^[a-fA-F0-9]{3,4}$/.test(normalized)) {
+    const [r, g, b] = normalized.split("");
+    if (!r || !g || !b) return null;
+    return {
+      r: Number.parseInt(`${r}${r}`, 16),
+      g: Number.parseInt(`${g}${g}`, 16),
+      b: Number.parseInt(`${b}${b}`, 16),
+    };
+  }
+
+  if (/^[a-fA-F0-9]{6,8}$/.test(normalized)) {
+    return {
+      r: Number.parseInt(normalized.slice(0, 2), 16),
+      g: Number.parseInt(normalized.slice(2, 4), 16),
+      b: Number.parseInt(normalized.slice(4, 6), 16),
+    };
+  }
+
+  return null;
+}
+
+function getOklabLightness(color: string): number | null {
+  const match = color
+    .trim()
+    .match(/^okl(?:ab|ch)\(\s*([+-]?(?:\d+\.?\d*|\.\d+))(%?)/i);
+  if (!match?.[1]) return null;
+
+  const lightness = Number.parseFloat(match[1]);
+  if (!Number.isFinite(lightness)) return null;
+
+  const normalizedLightness =
+    match[2] === "%" || lightness > 1 ? lightness / 100 : lightness;
+  return Math.min(Math.max(normalizedLightness, 0), 1);
+}
+
+export function getThemeForegroundColor(
+  color: string,
+  darkForeground = "#111827",
+): string {
+  const rgb = normalizeHexColorToRgb(color);
+  const oklabLightness = getOklabLightness(color);
+  if (!rgb && oklabLightness !== null) {
+    return oklabLightness > 0.6 ? darkForeground : "#ffffff";
+  }
+
+  if (!rgb) return "#ffffff";
+
+  const toLinear = (channel: number): number => {
+    const normalized = channel / 255;
+    return normalized <= 0.03928
+      ? normalized / 12.92
+      : ((normalized + 0.055) / 1.055) ** 2.4;
+  };
+
+  const luminance =
+    0.2126 * toLinear(rgb.r) +
+    0.7152 * toLinear(rgb.g) +
+    0.0722 * toLinear(rgb.b);
+  return luminance > 0.45 ? darkForeground : "#ffffff";
+}
+
+function getThemeColorVariables(themeColor: string): string[] {
+  const foreground = getThemeForegroundColor(themeColor);
+  const iconFilter = foreground === "#ffffff" ? "invert(1)" : "none";
+
+  return [
+    `--color-theme: ${themeColor};`,
+    `--color-theme-foreground: ${foreground};`,
+    `--color-theme-icon-filter: ${iconFilter};`,
+    "--color-theme-top: color-mix(in oklab, var(--color-theme) 88%, white);",
+    "--color-theme-bottom: color-mix(in oklab, var(--color-theme) 90%, black);",
+  ];
+}
+
+function getNeutralPaletteVariables(baseColor: BaseColorOption): string[] {
+  const palette = paletteColors[baseColor] ?? paletteColors.neutral;
+  return [
+    `--color-neutral: ${palette["500"]};`,
+    ...neutralColorShades.map(
+      (shade) => `--color-neutral-${shade}: ${palette[shade]};`,
+    ),
+  ];
+}
+
+export function getDocsBaseColorShade(
+  theme: DocsConfig["theme"],
+  mode: "light" | "dark",
+  shade: NeutralColorShade,
+): string {
+  const themeBaseColor = theme?.baseColor ?? "neutral";
+  const baseColor: BaseColorOption =
+    typeof themeBaseColor === "string" ? themeBaseColor : themeBaseColor[mode];
+  const palette = paletteColors[baseColor] ?? paletteColors.neutral;
+  return palette[shade];
+}
+
+export function getDocsLightBaseColorShade(
+  theme: DocsConfig["theme"],
+  shade: NeutralColorShade,
+): string {
+  return getDocsBaseColorShade(theme, "light", shade);
+}
+
+export function getDocsDarkBaseColorShade(
+  theme: DocsConfig["theme"],
+  shade: NeutralColorShade,
+): string {
+  return getDocsBaseColorShade(theme, "dark", shade);
+}
+
+export function getDocsThemeCss(theme: DocsConfig["theme"]): string {
+  const themeBaseColor = theme?.baseColor ?? "neutral";
+  const themeThemeColor = theme?.themeColor;
+  const lightBaseColor: BaseColorOption =
+    typeof themeBaseColor === "string" ? themeBaseColor : themeBaseColor.light;
+  const darkBaseColor: BaseColorOption =
+    typeof themeBaseColor === "string" ? themeBaseColor : themeBaseColor.dark;
+  const lightThemeColor =
+    typeof themeThemeColor === "string"
+      ? themeThemeColor
+      : (themeThemeColor?.light ?? DEFAULT_THEME_COLOR_LIGHT);
+  const darkThemeColor =
+    typeof themeThemeColor === "string"
+      ? themeThemeColor
+      : (themeThemeColor?.dark ?? DEFAULT_THEME_COLOR_DARK);
+
+  const lightNeutralVariables = getNeutralPaletteVariables(lightBaseColor);
+  const darkNeutralVariables = getNeutralPaletteVariables(darkBaseColor);
+  const lightThemeColorVariables = getThemeColorVariables(lightThemeColor);
+  const darkThemeColorVariables = getThemeColorVariables(darkThemeColor);
+
+  return [
+    "html[data-theme='light'], html:not(.dark):not([data-theme='dark']) {",
+    ...[...lightNeutralVariables, ...lightThemeColorVariables].map(
+      (declaration) => `  ${declaration.replace(/;$/, " !important;")}`,
+    ),
+    "}",
+    "html.dark, html[data-theme='dark'] {",
+    ...[...darkNeutralVariables, ...darkThemeColorVariables].map(
+      (declaration) => `  ${declaration.replace(/;$/, " !important;")}`,
+    ),
+    "}",
+  ].join("\n");
+}

package/template/src/lib/utils.ts

@@ -5,6 +5,7 @@ import remarkRehype from "remark-rehype";
 import rehypeStringify from "rehype-stringify";
 import rehypeExternalLinks from "./mdx/rehype-external-links";
 import path from "node:path";
+import { prependBasePath } from "./base-path";
 
 export function slugify(text: string): string {
   if (typeof text !== "string") {
@@ -66,7 +67,7 @@ export function buildMdxPageHref(args: {
   homePath?: string;
 }): string {
   if (args.homePath && args.filePath === args.homePath) {
-    return "/";
+    return prependBasePath("/");
   }
 
   const filename = path.basename(args.filePath);
@@ -75,9 +76,11 @@ export function buildMdxPageHref(args: {
     .replace(/^\/+/, "")
     .replace(/\/+$/, "");
 
-  return normalizedGroupSlug
+  const href = normalizedGroupSlug
     ? `/${normalizedGroupSlug}/${pageSlug}`
     : `/${pageSlug}`;
+
+  return prependBasePath(href);
 }
 
 export function parseOpenApiEndpoint(
@@ -103,7 +106,10 @@ export function parseOpenApiEndpoint(
   };
 }
 
-export function buildOpenApiEndpointSlug(pathStr: string, method: string): string {
+export function buildOpenApiEndpointSlug(
+  pathStr: string,
+  method: string,
+): string {
   const normalizedPath = pathStr.startsWith("/") ? pathStr : `/${pathStr}`;
   const pathSlug = normalizedPath
     .replace(/^\//, "")
@@ -123,7 +129,9 @@ export function buildOpenApiEndpointHref(args: {
     .replace(/^\/+/, "")
     .replace(/\/+$/, "");
 
-  return normalizedGroupSlug
+  const href = normalizedGroupSlug
     ? `/${normalizedGroupSlug}/${endpointSlug}`
     : `/${endpointSlug}`;
+
+  return prependBasePath(href);
 }