radiant-docs 0.1.38 → 0.1.40

package/template/src/lib/validation.ts

@@ -167,22 +167,58 @@ export type NavbarItem = {
   href: string;
   icon?: string | null;
 };
-export type LogoVariant = string | {
-  image: string;
-  padding?: {
-    top?: number;
-    bottom?: number;
-  };
+export type HiddenPageRoute = {
+  filePath: string;
+  href: string;
 };
+type InternalPageHrefResolution = HiddenPageRoute & {
+  linkHref: string;
+};
+export type LogoVariant =
+  | string
+  | {
+      image: string;
+      padding?: {
+        top?: number;
+        bottom?: number;
+      };
+    };
 export type Logo = {
   light?: LogoVariant;
   dark?: LogoVariant;
   href?: string;
   pill?: string | false;
 };
+export const BASE_COLOR_OPTIONS = [
+  "slate",
+  "gray",
+  "zinc",
+  "neutral",
+  "stone",
+  "taupe",
+  "mauve",
+  "mist",
+  "olive",
+] as const;
+export type BaseColorOption = (typeof BASE_COLOR_OPTIONS)[number];
+export type BaseColorByMode = {
+  light: BaseColorOption;
+  dark: BaseColorOption;
+};
+export const DEFAULT_THEME_COLOR_LIGHT = "#171717";
+export const DEFAULT_THEME_COLOR_DARK = "#f5f5f5";
+export type ThemeColorByMode = {
+  light: string;
+  dark: string;
+};
+export type DocsTheme = {
+  baseColor?: BaseColorOption | BaseColorByMode;
+  themeColor?: string | ThemeColorByMode;
+};
 export type DocsConfig = {
   title: string;
   logo?: Logo;
+  theme?: DocsTheme;
   home?: string;
   navigation: NavigationItem;
   navbar?: {
@@ -195,6 +231,7 @@ export type DocsConfig = {
     proxy?: boolean;
   };
   footer?: Footer;
+  hiddenPageRoutes?: HiddenPageRoute[];
 };
 
 export type SocialPlatform =
@@ -295,6 +332,54 @@ function normalizeDocsPagePath(
   return normalizedPath;
 }
 
+function splitHrefPathAndSuffix(href: string): {
+  pathname: string;
+  suffix: string;
+} {
+  const match = href.match(/^([^?#]*)(.*)$/);
+  return {
+    pathname: match?.[1] ?? href,
+    suffix: match?.[2] ?? "",
+  };
+}
+
+function normalizeInternalPageHref(
+  href: string,
+  currentPath: Path,
+  label: string,
+): InternalPageHrefResolution | null {
+  const trimmedHref = href.trim();
+  if (trimmedHref === "") {
+    throwConfigError(`${label} cannot be an empty string`, currentPath);
+  }
+
+  if (isUrl(trimmedHref)) {
+    return null;
+  }
+
+  if (!trimmedHref.startsWith("/")) {
+    throwConfigError(
+      `${label} must be either a valid URL (http:// or https://) or an internal path (starting with /)`,
+      currentPath,
+    );
+  }
+
+  const { pathname, suffix } = splitHrefPathAndSuffix(trimmedHref);
+  const normalizedPathname = pathname.replace(/\/{2,}/g, "/");
+  if (normalizedPathname === "/" || normalizedPathname === "") {
+    return null;
+  }
+
+  const filePath = normalizeDocsPagePath(normalizedPathname, currentPath, label);
+  validateFileExistence(filePath, currentPath);
+
+  return {
+    filePath,
+    href: `/${filePath}`,
+    linkHref: `/${filePath}${suffix}`,
+  };
+}
+
 // Cache for OpenAPI specs (key: filePathOrUrl, value: parsed spec)
 const openApiSpecCache = new Map<string, any>();
 
@@ -662,7 +747,11 @@ async function validateNavigationNode(
         continue;
       }
 
-      await validateNavigationNode(child, [...path, "pages", i], groupDepth + 1);
+      await validateNavigationNode(
+        child,
+        [...path, "pages", i],
+        groupDepth + 1,
+      );
     }
     return;
   }
@@ -1049,9 +1138,12 @@ async function validateNavMenu(menu: any, currentPath: Path) {
   }
 }
 
-function validateNavbarItem(item: any, currentPath: Path): void {
+function validateNavbarItem(
+  item: any,
+  currentPath: Path,
+): HiddenPageRoute | null {
   // Check if object exists, otherwise we skip (it's optional)
-  if (item === undefined) return;
+  if (item === undefined) return null;
 
   checkType(item, "object", currentPath, "Navbar item");
 
@@ -1069,8 +1161,18 @@ function validateNavbarItem(item: any, currentPath: Path): void {
     ]);
   }
 
+  const hiddenPageRoute = normalizeInternalPageHref(
+    item.href,
+    [...currentPath, "href"],
+    "Navbar item href",
+  );
+  if (hiddenPageRoute) {
+    item.href = hiddenPageRoute.linkHref;
+  }
+
   // Optional property
   validateIcon(item.icon, [...currentPath, "icon"]);
+  return hiddenPageRoute;
 }
 
 // --- Top-Level Validation Functions (Your Clean API) ---
@@ -1080,7 +1182,11 @@ function validateTitle(title: DocsConfig["title"]) {
   if (!title) throwConfigError("Title is missing.", ["title"]);
 }
 
-function validateLogoPaddingValue(value: unknown, currentPath: Path, label: string): void {
+function validateLogoPaddingValue(
+  value: unknown,
+  currentPath: Path,
+  label: string,
+): void {
   if (value === undefined) return;
 
   if (typeof value !== "number" || !Number.isFinite(value)) {
@@ -1134,7 +1240,11 @@ function validateLogoVariant(
     return;
   }
 
-  if (typeof variant !== "object" || variant === null || Array.isArray(variant)) {
+  if (
+    typeof variant !== "object" ||
+    variant === null ||
+    Array.isArray(variant)
+  ) {
     throwConfigError(
       `Logo ${mode} must be a string path or an object with 'image' and optional 'padding'.`,
       currentPath,
@@ -1152,13 +1262,17 @@ function validateLogoVariant(
   }
 
   if (typeof variant.image !== "string") {
-    throwConfigError(
-      `Logo ${mode} object must include an 'image' string.`,
-      [...currentPath, "image"],
-    );
+    throwConfigError(`Logo ${mode} object must include an 'image' string.`, [
+      ...currentPath,
+      "image",
+    ]);
   }
 
-  validateLogoImagePath(variant.image, [...currentPath, "image"], `Logo ${mode} image`);
+  validateLogoImagePath(
+    variant.image,
+    [...currentPath, "image"],
+    `Logo ${mode} image`,
+  );
 
   if (variant.padding === undefined) return;
 
@@ -1242,10 +1356,214 @@ function validateLogo(logo: DocsConfig["logo"]) {
         );
       }
     } else if (logo.pill !== false) {
-      throwConfigError("Logo pill must be a string or false.", ["logo", "pill"]);
+      throwConfigError("Logo pill must be a string or false.", [
+        "logo",
+        "pill",
+      ]);
     }
   }
+}
+
+function validateTheme(theme: DocsConfig["theme"]): void {
+  if (theme === undefined) return;
+
+  checkType(theme, "object", ["theme"], "Theme configuration");
+  if (typeof theme !== "object" || theme === null || Array.isArray(theme)) {
+    throwConfigError("Theme configuration must be an object.", ["theme"]);
+  }
+
+  const normalizeBaseColor = (
+    value: unknown,
+    currentPath: Path,
+    label: string,
+  ): BaseColorOption => {
+    checkType(value, "string", currentPath, label);
+    if (typeof value !== "string") {
+      throwConfigError(`${label} must be a string.`, currentPath);
+    }
+
+    const normalizedBaseColor = (value as string).trim().toLowerCase();
+    if (normalizedBaseColor.length === 0) {
+      throwConfigError(`${label} cannot be empty.`, currentPath);
+    }
+
+    if (!BASE_COLOR_OPTIONS.includes(normalizedBaseColor as BaseColorOption)) {
+      throwConfigError(
+        `${label} must be one of: ${BASE_COLOR_OPTIONS.join(", ")}.`,
+        currentPath,
+      );
+    }
+
+    return normalizedBaseColor as BaseColorOption;
+  };
+
+  const normalizeThemeColor = (
+    value: unknown,
+    currentPath: Path,
+    label: string,
+  ): string => {
+    checkType(value, "string", currentPath, label);
+    if (typeof value !== "string") {
+      throwConfigError(`${label} must be a string.`, currentPath);
+    }
 
+    const trimmedValue = (value as string).trim();
+    if (trimmedValue.length === 0) {
+      throwConfigError(`${label} cannot be empty.`, currentPath);
+    }
+
+    const normalizedValue = trimmedValue.startsWith("#")
+      ? trimmedValue
+      : `#${trimmedValue}`;
+    if (
+      !/^#(?:[A-Fa-f0-9]{3}|[A-Fa-f0-9]{4}|[A-Fa-f0-9]{6}|[A-Fa-f0-9]{8})$/.test(
+        normalizedValue,
+      )
+    ) {
+      throwConfigError(
+        `${label} must be a valid hex color (for example: #1d4ed8).`,
+        currentPath,
+      );
+    }
+
+    return normalizedValue.toLowerCase();
+  };
+
+  if (theme.baseColor !== undefined) {
+    if (typeof theme.baseColor === "string") {
+      theme.baseColor = normalizeBaseColor(
+        theme.baseColor,
+        ["theme", "baseColor"],
+        "Theme base color",
+      );
+    } else {
+      checkType(
+        theme.baseColor,
+        "object",
+        ["theme", "baseColor"],
+        "Theme base color",
+      );
+      if (
+        typeof theme.baseColor !== "object" ||
+        theme.baseColor === null ||
+        Array.isArray(theme.baseColor)
+      ) {
+        throwConfigError(
+          "Theme base color must be a string or an object with light/dark values.",
+          ["theme", "baseColor"],
+        );
+      }
+
+      const baseColorByMode = theme.baseColor as Record<string, unknown>;
+      const allowedKeys = new Set(["light", "dark"]);
+      for (const key of Object.keys(baseColorByMode)) {
+        if (!allowedKeys.has(key)) {
+          throwConfigError(
+            "Theme base color object only supports 'light' and 'dark'.",
+            ["theme", "baseColor", key],
+          );
+        }
+      }
+
+      const light =
+        baseColorByMode.light !== undefined
+          ? normalizeBaseColor(
+              baseColorByMode.light,
+              ["theme", "baseColor", "light"],
+              "Theme base color light",
+            )
+          : undefined;
+      const dark =
+        baseColorByMode.dark !== undefined
+          ? normalizeBaseColor(
+              baseColorByMode.dark,
+              ["theme", "baseColor", "dark"],
+              "Theme base color dark",
+            )
+          : undefined;
+
+      if (!light && !dark) {
+        throwConfigError(
+          "Theme base color object must include 'light', 'dark', or both.",
+          ["theme", "baseColor"],
+        );
+      }
+
+      const resolvedLight: BaseColorOption = light ?? "neutral";
+      const resolvedDark: BaseColorOption = dark ?? "neutral";
+
+      theme.baseColor = {
+        light: resolvedLight,
+        dark: resolvedDark,
+      };
+    }
+  }
+
+  if (theme.themeColor === undefined) {
+    return;
+  }
+
+  if (typeof theme.themeColor === "string") {
+    theme.themeColor = normalizeThemeColor(
+      theme.themeColor,
+      ["theme", "themeColor"],
+      "Theme color",
+    );
+    return;
+  }
+
+  checkType(theme.themeColor, "object", ["theme", "themeColor"], "Theme color");
+  if (
+    typeof theme.themeColor !== "object" ||
+    theme.themeColor === null ||
+    Array.isArray(theme.themeColor)
+  ) {
+    throwConfigError(
+      "Theme color must be a string or an object with light/dark values.",
+      ["theme", "themeColor"],
+    );
+  }
+
+  const themeColorByMode = theme.themeColor as Record<string, unknown>;
+  const allowedKeys = new Set(["light", "dark"]);
+  for (const key of Object.keys(themeColorByMode)) {
+    if (!allowedKeys.has(key)) {
+      throwConfigError("Theme color object only supports 'light' and 'dark'.", [
+        "theme",
+        "themeColor",
+        key,
+      ]);
+    }
+  }
+
+  const light =
+    themeColorByMode.light !== undefined
+      ? normalizeThemeColor(
+          themeColorByMode.light,
+          ["theme", "themeColor", "light"],
+          "Theme color light",
+        )
+      : undefined;
+  const dark =
+    themeColorByMode.dark !== undefined
+      ? normalizeThemeColor(
+          themeColorByMode.dark,
+          ["theme", "themeColor", "dark"],
+          "Theme color dark",
+        )
+      : undefined;
+
+  if (!light && !dark) {
+    throwConfigError(
+      "Theme color object must include 'light', 'dark', or both.",
+      ["theme", "themeColor"],
+    );
+  }
+
+  theme.themeColor = {
+    light: light ?? DEFAULT_THEME_COLOR_LIGHT,
+    dark: dark ?? DEFAULT_THEME_COLOR_DARK,
+  };
 }
 
 function validateHome(home: DocsConfig["home"]): string | undefined {
@@ -1256,8 +1574,9 @@ function validateHome(home: DocsConfig["home"]): string | undefined {
   return normalizedHome;
 }
 
-function validateNavbar(navbar: DocsConfig["navbar"]) {
-  if (navbar === undefined) return; // Navbar itself is optional
+function validateNavbar(navbar: DocsConfig["navbar"]): HiddenPageRoute[] {
+  const hiddenPageRoutes: HiddenPageRoute[] = [];
+  if (navbar === undefined) return hiddenPageRoutes; // Navbar itself is optional
 
   checkType(navbar, "object", ["navbar"], "Navbar configuration");
 
@@ -1265,10 +1584,18 @@ function validateNavbar(navbar: DocsConfig["navbar"]) {
   checkType(navbar.blur, "boolean", ["navbar", "blur"], "Navbar blur setting");
 
   // Validate 'primary' item
-  validateNavbarItem(navbar.primary, ["navbar", "primary"]);
+  const primaryPageRoute = validateNavbarItem(navbar.primary, [
+    "navbar",
+    "primary",
+  ]);
+  if (primaryPageRoute) hiddenPageRoutes.push(primaryPageRoute);
 
   // Validate 'secondary' item
-  validateNavbarItem(navbar.secondary, ["navbar", "secondary"]);
+  const secondaryPageRoute = validateNavbarItem(navbar.secondary, [
+    "navbar",
+    "secondary",
+  ]);
+  if (secondaryPageRoute) hiddenPageRoutes.push(secondaryPageRoute);
 
   // Validate 'links' array
   if (navbar.links !== undefined) {
@@ -1282,13 +1609,17 @@ function validateNavbar(navbar: DocsConfig["navbar"]) {
     }
 
     navbar.links.forEach((link: any, i: number) => {
-      validateNavbarItem(link, ["navbar", "links", i]);
+      const hiddenPageRoute = validateNavbarItem(link, ["navbar", "links", i]);
+      if (hiddenPageRoute) hiddenPageRoutes.push(hiddenPageRoute);
     });
   }
+
+  return hiddenPageRoutes;
 }
 
-function validateFooter(footer: DocsConfig["footer"]) {
-  if (footer === undefined) return;
+function validateFooter(footer: DocsConfig["footer"]): HiddenPageRoute[] {
+  const hiddenPageRoutes: HiddenPageRoute[] = [];
+  if (footer === undefined) return hiddenPageRoutes;
 
   checkType(footer, "object", ["footer"], "Footer configuration");
 
@@ -1367,19 +1698,19 @@ function validateFooter(footer: DocsConfig["footer"]) {
         ]);
       }
 
-      const trimmedHref = link.href.trim();
-      const isExternal =
-        trimmedHref.startsWith("http://") || trimmedHref.startsWith("https://");
-      const isInternal = trimmedHref.startsWith("/");
-
-      if (!isExternal && !isInternal) {
-        throwConfigError(
-          "Footer link href must be either a valid URL (http:// or https://) or an internal path (starting with /)",
-          ["footer", "links", i, "href"],
-        );
+      const hiddenPageRoute = normalizeInternalPageHref(
+        link.href,
+        ["footer", "links", i, "href"],
+        "Footer link href",
+      );
+      if (hiddenPageRoute) {
+        link.href = hiddenPageRoute.linkHref;
+        hiddenPageRoutes.push(hiddenPageRoute);
       }
     });
   }
+
+  return hiddenPageRoutes;
 }
 
 async function validateNavigation(navigation: DocsConfig["navigation"]) {
@@ -1433,8 +1764,7 @@ async function validateConfig(config: any): Promise<DocsConfig> {
   // Execute top-level checks sequentially
   validateTitle(config.title);
   validateLogo(config.logo);
-  validateNavbar(config.navbar);
-  validateFooter(config.footer);
+  validateTheme(config.theme);
   await validateNavigation(config.navigation);
   config.home = validateHome(config.home);
 
@@ -1449,6 +1779,16 @@ async function validateConfig(config: any): Promise<DocsConfig> {
     config.home = fallbackHome;
   }
 
+  const hiddenPageRoutes = [
+    ...validateNavbar(config.navbar),
+    ...validateFooter(config.footer),
+  ];
+  const dedupedHiddenPageRoutes = new Map<string, HiddenPageRoute>();
+  for (const route of hiddenPageRoutes) {
+    dedupedHiddenPageRoutes.set(route.href, route);
+  }
+  config.hiddenPageRoutes = Array.from(dedupedHiddenPageRoutes.values());
+
   // --- 4. Validate Playground ---
   if (config.playground !== undefined) {
     checkType(config.playground, "object", ["playground"], "Playground");

package/template/src/pages/404.astro

@@ -1,5 +1,6 @@
 ---
 import { Icon } from "astro-icon/components";
+import { withBasePath } from "../lib/base-path";
 import Layout from "../layouts/Layout.astro";
 ---
 
@@ -33,7 +34,7 @@ import Layout from "../layouts/Layout.astro";
         Go back
       </button>
       <a
-        href="/"
+        href={withBasePath("/")}
         class="inline-flex items-center justify-center gap-2 rounded-lg [corner-shape:superellipse(1.2)] border border-border px-4 py-2 text-sm font-[350] dark:font-[450] text-white bg-linear-to-b from-neutral-900/85 to-neutral-900 dark:from-neutral-100 dark:to-neutral-200 shadow-sm"
       >
         <Icon name="lucide:house" class="size-4" />

package/template/src/pages/[...slug].astro

@@ -1,16 +1,48 @@
 ---
 import { getCollection } from "astro:content";
-import { getAllRoutes, resolveMdxPageTitle, type Route } from "../lib/routes";
+import {
+  getAllRoutes,
+  resolveMdxPageTitle,
+  type Route,
+} from "../lib/routes";
 import { getConfig, validateMdxContent } from "../lib/validation";
 import MdxPage from "../components/MdxPage.astro";
 import OpenApiPage from "../components/OpenApiPage.astro";
 import type { GetStaticPathsResult } from "astro";
 
 export async function getStaticPaths(): Promise<GetStaticPathsResult> {
+  const buildAdjacentRouteMap = (routes: Route[]): Map<
+    string,
+    {
+      previousRoute?: Route;
+      nextRoute?: Route;
+    }
+  > => {
+    const adjacentBySlug = new Map<
+      string,
+      {
+        previousRoute?: Route;
+        nextRoute?: Route;
+      }
+    >();
+
+    for (let index = 0; index < routes.length; index++) {
+      const currentRoute = routes[index];
+      adjacentBySlug.set(currentRoute.slug, {
+        previousRoute: routes[index - 1],
+        nextRoute: routes[index + 1],
+      });
+    }
+
+    return adjacentBySlug;
+  };
+
   await validateMdxContent();
   const routes = await getAllRoutes();
+  const visibleRoutes = routes.filter((route) => !route.hidden);
   const docs = await getCollection("docs");
   const config = await getConfig();
+  const adjacentRoutesBySlug = buildAdjacentRouteMap(visibleRoutes);
 
   // console.log("routes", routes);
 
@@ -31,9 +63,16 @@ export async function getStaticPaths(): Promise<GetStaticPathsResult> {
           `Could not find content collection entry for path: ${route.filePath}`,
         );
       }
+      const adjacentRoutes = adjacentRoutesBySlug.get(route.slug);
       return {
         params: { slug: route.slug },
-        props: { route, entry },
+        props: {
+          route,
+          entry,
+          previousRoute: adjacentRoutes?.previousRoute,
+          nextRoute: adjacentRoutes?.nextRoute,
+          homePath: config.home,
+        },
       };
     } else {
       return {
@@ -68,22 +107,45 @@ export async function getStaticPaths(): Promise<GetStaticPathsResult> {
           filePath: config.home,
         }),
     };
+
+    const homeAdjacentRoutes = existingHomeRoute
+      ? adjacentRoutesBySlug.get(existingHomeRoute.slug)
+      : undefined;
+
     paths.push({
       params: { slug: "/" },
-      props: { route: homeRoute, entry: homeEntry },
+      props: {
+        route: homeRoute,
+        entry: homeEntry,
+        previousRoute: homeAdjacentRoutes?.previousRoute,
+        nextRoute: homeAdjacentRoutes?.nextRoute,
+        homePath: config.home,
+      },
     });
   }
 
   return paths;
 }
 
-const props = Astro.props as { route: Route; entry?: any };
-const { route, entry } = props;
+const props = Astro.props as {
+  route: Route;
+  entry?: any;
+  previousRoute?: Route;
+  nextRoute?: Route;
+  homePath?: string;
+};
+const { route, entry, previousRoute, nextRoute, homePath } = props;
 ---
 
 {
   route.type === "mdx" ? (
-    <MdxPage entry={entry!} route={route} />
+    <MdxPage
+      entry={entry!}
+      route={route}
+      previousRoute={previousRoute}
+      nextRoute={nextRoute}
+      homePath={homePath}
+    />
   ) : (
     <OpenApiPage route={route} />
   )