radiant-docs 0.1.61 → 0.1.62

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

@@ -9,10 +9,12 @@ import {
   resolveDocsHref,
   type DocsConfig,
   type NavGroup,
+  type NavMenu,
   type NavMenuItem,
   type NavOpenApi,
   type NavOpenApiPage,
   type NavPage,
+  type NavTabItem,
 } from "../validation";
 import { prependBasePath, withBasePath } from "../base-path";
 import {
@@ -26,6 +28,11 @@ import {
 } from "../utils";
 
 type MdxNavItem = string | NavPage | NavGroup | NavOpenApiPage;
+type NavigationContentContainer = {
+  pages?: MdxNavItem[];
+  menu?: NavMenu;
+  openapi?: string | NavOpenApi;
+};
 
 type AuxiliaryPageRef = {
   filePath: string;
@@ -36,9 +43,24 @@ type DocsConfigWithAuxiliaryRefs = DocsConfig & {
   auxiliaryPageRefs?: AuxiliaryPageRef[];
 };
 
+type OpenApiEndpointLinkRef = {
+  source?: string;
+  method: string;
+  path: string;
+  endpoint: string;
+};
+
+type OpenApiEndpointRouteTarget = OpenApiEndpointLinkRef & {
+  source: string;
+  targetKey: string;
+};
+
 type ResolvedRouteIndex = {
   canonicalHrefByFilePath: Map<string, string>;
   allHrefsByFilePath: Map<string, string[]>;
+  canonicalHrefByOpenApiEndpointKey: Map<string, string>;
+  allHrefsByOpenApiEndpointKey: Map<string, string[]>;
+  openApiEndpointTargetsByEndpoint: Map<string, OpenApiEndpointRouteTarget[]>;
   validRoutePaths: Set<string>;
   allDocsFilePaths: Set<string>;
   routeSlugs: ReturnType<typeof createRouteSlugRegistry>;
@@ -76,10 +98,24 @@ const HTTP_METHODS = [
   "options",
   "trace",
 ];
+const HTTP_METHOD_SET = new Set<string>(HTTP_METHODS);
 
 let cachedRouteIndex: ResolvedRouteIndex | null = null;
 let cachedConfig: DocsConfig | null = null;
 
+function isUrl(value: string): boolean {
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+function containsPathTraversal(value: string): boolean {
+  return value.replace(/\\/g, "/").split("/").includes("..");
+}
+
 function normalizeDocsFilePath(value: string): string {
   let normalized = value.replace(/\\/g, "/").trim();
   if (!normalized) return "";
@@ -94,6 +130,102 @@ function normalizeDocsFilePath(value: string): string {
   return posixNormalized === "." ? "" : posixNormalized;
 }
 
+function normalizeOpenApiLinkSource(source: string): string {
+  const trimmedSource = source.trim();
+  if (isUrl(trimmedSource)) {
+    return trimmedSource;
+  }
+
+  let normalizedSource = trimmedSource.replace(/\\/g, "/").trim();
+  normalizedSource = normalizedSource.replace(/^\/+/, "").replace(/\/+$/, "");
+  normalizedSource = normalizedSource.replace(/^src\/content\/docs\//, "");
+
+  const posixNormalized = path.posix
+    .normalize(`/${normalizedSource}`)
+    .replace(/^\/+/, "");
+
+  return posixNormalized === "." ? "" : posixNormalized;
+}
+
+function formatOpenApiEndpoint(
+  method: string,
+  endpointPath: string,
+): string {
+  return `${method.toUpperCase()} ${endpointPath.toLowerCase()}`;
+}
+
+function formatOpenApiEndpointTargetKey(
+  source: string,
+  method: string,
+  endpointPath: string,
+): string {
+  return `${normalizeOpenApiLinkSource(source)}\0${formatOpenApiEndpoint(
+    method,
+    endpointPath,
+  )}`;
+}
+
+function parseOpenApiEndpointLinkEndpoint(
+  endpointStr: string,
+): Pick<OpenApiEndpointLinkRef, "method" | "path" | "endpoint"> | null {
+  const trimmed = endpointStr.trim();
+  const parts = trimmed.split(/\s+/);
+
+  if (parts.length !== 2) {
+    return null;
+  }
+
+  const method = parts[0].toUpperCase();
+  const endpointPath = parts[1];
+  if (
+    !HTTP_METHOD_SET.has(method.toLowerCase()) ||
+    !endpointPath.startsWith("/")
+  ) {
+    return null;
+  }
+
+  const normalizedPath = endpointPath.toLowerCase();
+  return {
+    method,
+    path: normalizedPath,
+    endpoint: formatOpenApiEndpoint(method, normalizedPath),
+  };
+}
+
+function parseOpenApiEndpointLinkHref(
+  href: string,
+): OpenApiEndpointLinkRef | null {
+  const trimmedHref = href.trim();
+  if (!trimmedHref) return null;
+
+  const hashIndex = trimmedHref.indexOf("#");
+  if (hashIndex > 0) {
+    const rawSource = trimmedHref.slice(0, hashIndex).trim();
+    if (!isUrl(rawSource) && containsPathTraversal(rawSource)) {
+      return null;
+    }
+
+    const source = normalizeOpenApiLinkSource(rawSource);
+    if (!source) {
+      return null;
+    }
+
+    const parsedEndpoint = parseOpenApiEndpointLinkEndpoint(
+      trimmedHref.slice(hashIndex + 1),
+    );
+    if (!parsedEndpoint) {
+      return null;
+    }
+
+    return {
+      source,
+      ...parsedEndpoint,
+    };
+  }
+
+  return parseOpenApiEndpointLinkEndpoint(trimmedHref);
+}
+
 function normalizeRoutePath(value: string): string {
   const trimmed = value.trim();
   if (!trimmed || trimmed === "/") {
@@ -208,6 +340,38 @@ function addMdxRoute(args: {
   args.index.allHrefsByFilePath.set(normalizedFilePath, aliases);
 }
 
+function createOpenApiEndpointRouteTarget(args: {
+  source: string;
+  method: string;
+  endpointPath: string;
+}): OpenApiEndpointRouteTarget {
+  const source = normalizeOpenApiLinkSource(args.source);
+  const endpoint = formatOpenApiEndpoint(args.method, args.endpointPath);
+
+  return {
+    source,
+    method: args.method.toUpperCase(),
+    path: args.endpointPath.toLowerCase(),
+    endpoint,
+    targetKey: formatOpenApiEndpointTargetKey(
+      source,
+      args.method,
+      args.endpointPath,
+    ),
+  };
+}
+
+function addOpenApiEndpointTargetToMap(
+  map: Map<string, OpenApiEndpointRouteTarget[]>,
+  target: OpenApiEndpointRouteTarget,
+): void {
+  const targets = map.get(target.endpoint) ?? [];
+  if (!targets.some((candidate) => candidate.targetKey === target.targetKey)) {
+    targets.push(target);
+  }
+  map.set(target.endpoint, targets);
+}
+
 function addOpenApiEndpointRoute(args: {
   index: ResolvedRouteIndex;
   parentSlug: string;
@@ -232,10 +396,30 @@ function addOpenApiEndpointRoute(args: {
     }),
     identity: `openapi:${args.source}:${args.method.toUpperCase()} ${args.endpointPath.toLowerCase()}`,
   }).slug;
-  addValidRoutePath(
+  const href = addValidRoutePath(
     args.index,
     prependBasePath(`/${registeredSlug}`),
   );
+  const target = createOpenApiEndpointRouteTarget({
+    source: args.source,
+    method: args.method,
+    endpointPath: args.endpointPath,
+  });
+
+  if (!args.index.canonicalHrefByOpenApiEndpointKey.has(target.targetKey)) {
+    args.index.canonicalHrefByOpenApiEndpointKey.set(target.targetKey, href);
+  }
+
+  const aliases =
+    args.index.allHrefsByOpenApiEndpointKey.get(target.targetKey) ?? [];
+  if (!aliases.includes(href)) {
+    aliases.push(href);
+  }
+  args.index.allHrefsByOpenApiEndpointKey.set(target.targetKey, aliases);
+  addOpenApiEndpointTargetToMap(
+    args.index.openApiEndpointTargetsByEndpoint,
+    target,
+  );
 }
 
 function addAuxiliaryPageRef(
@@ -414,27 +598,69 @@ async function processMenuItems(args: {
   index: ResolvedRouteIndex;
   homePath: string | null;
   items: NavMenuItem[];
+  parentSlug?: string;
 }): Promise<void> {
   for (const menuItem of args.items) {
     const menuSlug = slugify(menuItem.label);
-    const parentSlug = menuSlug;
+    const parentSlug = args.parentSlug
+      ? `${args.parentSlug}/${menuSlug}`
+      : menuSlug;
+
+    await processNavigationContent({
+      index: args.index,
+      parentSlug,
+      homePath: args.homePath,
+      item: menuItem,
+    });
+  }
+}
 
-    if (Array.isArray(menuItem.submenu.pages)) {
-      await processPages({
-        index: args.index,
-        parentSlug,
-        homePath: args.homePath,
-        items: menuItem.submenu.pages as MdxNavItem[],
-      });
-    }
+async function processTabItems(args: {
+  index: ResolvedRouteIndex;
+  homePath: string | null;
+  items: NavTabItem[];
+}): Promise<void> {
+  for (const tabItem of args.items) {
+    const tabSlug = slugify(tabItem.slug || tabItem.label);
+    await processNavigationContent({
+      index: args.index,
+      parentSlug: tabSlug,
+      homePath: args.homePath,
+      item: tabItem,
+    });
+  }
+}
 
-    if (menuItem.submenu.openapi) {
-      await processOpenApiFile({
-        index: args.index,
-        parentSlug,
-        openApiPathOrConfig: menuItem.submenu.openapi,
-      });
-    }
+async function processNavigationContent(args: {
+  index: ResolvedRouteIndex;
+  parentSlug: string;
+  homePath: string | null;
+  item: NavigationContentContainer;
+}): Promise<void> {
+  if (Array.isArray(args.item.pages)) {
+    await processPages({
+      index: args.index,
+      parentSlug: args.parentSlug,
+      homePath: args.homePath,
+      items: args.item.pages as MdxNavItem[],
+    });
+  }
+
+  if (args.item.menu?.items) {
+    await processMenuItems({
+      index: args.index,
+      parentSlug: args.parentSlug,
+      homePath: args.homePath,
+      items: args.item.menu.items,
+    });
+  }
+
+  if (args.item.openapi) {
+    await processOpenApiFile({
+      index: args.index,
+      parentSlug: args.parentSlug,
+      openApiPathOrConfig: args.item.openapi,
+    });
   }
 }
 
@@ -444,6 +670,12 @@ async function buildRouteIndex(
   const index: ResolvedRouteIndex = {
     canonicalHrefByFilePath: new Map<string, string>(),
     allHrefsByFilePath: new Map<string, string[]>(),
+    canonicalHrefByOpenApiEndpointKey: new Map<string, string>(),
+    allHrefsByOpenApiEndpointKey: new Map<string, string[]>(),
+    openApiEndpointTargetsByEndpoint: new Map<
+      string,
+      OpenApiEndpointRouteTarget[]
+    >(),
     validRoutePaths: new Set<string>(),
     allDocsFilePaths: new Set<string>(),
     routeSlugs: createRouteSlugRegistry(),
@@ -473,6 +705,14 @@ async function buildRouteIndex(
     });
   }
 
+  if (config.navigation.tabs?.items) {
+    await processTabItems({
+      index,
+      homePath,
+      items: config.navigation.tabs.items,
+    });
+  }
+
   const rootOpenApi = (config.navigation as any).openapi;
   if (
     typeof rootOpenApi === "string" ||
@@ -527,12 +767,89 @@ function buildInternalLinkRewriteError(args: {
   );
 }
 
+function formatOpenApiEndpointSourceList(
+  targets: OpenApiEndpointRouteTarget[],
+): string {
+  const sources = [...new Set(targets.map((target) => target.source))];
+  return sources.map((source) => `"${source}"`).join(", ");
+}
+
+function resolveOpenApiEndpointLinkToCanonicalHref(args: {
+  rawHref: string;
+  endpointLink: OpenApiEndpointLinkRef;
+  currentDocFilePath: string | null;
+  routeIndex: ResolvedRouteIndex;
+  warn: (message: string) => void;
+}): string {
+  const target =
+    args.endpointLink.source !== undefined
+      ? {
+          source: args.endpointLink.source,
+          targetKey: formatOpenApiEndpointTargetKey(
+            args.endpointLink.source,
+            args.endpointLink.method,
+            args.endpointLink.path,
+          ),
+        }
+      : (() => {
+          const targets =
+            args.routeIndex.openApiEndpointTargetsByEndpoint.get(
+              args.endpointLink.endpoint,
+            ) ?? [];
+          if (targets.length === 1) {
+            return targets[0];
+          }
+
+          throw buildInternalLinkRewriteError({
+            rawHref: args.rawHref,
+            currentDocFilePath: args.currentDocFilePath,
+            detail:
+              targets.length > 1
+                ? `The endpoint "${args.endpointLink.endpoint}" is ambiguous across OpenAPI sources (${formatOpenApiEndpointSourceList(
+                    targets,
+                  )}).`
+                : `No generated OpenAPI endpoint route matched "${args.endpointLink.endpoint}".`,
+          });
+        })();
+
+  const canonicalHref =
+    args.routeIndex.canonicalHrefByOpenApiEndpointKey.get(target.targetKey);
+  if (!canonicalHref) {
+    throw buildInternalLinkRewriteError({
+      rawHref: args.rawHref,
+      currentDocFilePath: args.currentDocFilePath,
+      detail: `The OpenAPI endpoint "${args.endpointLink.endpoint}" from "${target.source}" did not resolve to a canonical route.`,
+    });
+  }
+
+  const aliases =
+    args.routeIndex.allHrefsByOpenApiEndpointKey.get(target.targetKey) ?? [];
+  if (aliases.length > 1) {
+    args.warn(
+      `[INTERNAL_LINK_WARNING] "${args.rawHref}" matched OpenAPI endpoint "${args.endpointLink.endpoint}" in "${target.source}", which has multiple URLs (${aliases.join(", ")}). Rewriting to canonical URL "${canonicalHref}".`,
+    );
+  }
+
+  return withBasePath(canonicalHref);
+}
+
 function resolveLinkToCanonicalHref(args: {
   rawHref: string;
   currentDocFilePath: string | null;
   routeIndex: ResolvedRouteIndex;
   warn: (message: string) => void;
 }): string | null {
+  const endpointLink = parseOpenApiEndpointLinkHref(args.rawHref);
+  if (endpointLink) {
+    return resolveOpenApiEndpointLinkToCanonicalHref({
+      rawHref: args.rawHref,
+      endpointLink,
+      currentDocFilePath: args.currentDocFilePath,
+      routeIndex: args.routeIndex,
+      warn: args.warn,
+    });
+  }
+
   const resolvedHref = resolveDocsHref(args.rawHref);
   if (resolvedHref.kind === "ignored" || resolvedHref.kind === "local-asset") {
     return null;

package/template/src/lib/routes.ts

@@ -3,7 +3,9 @@ import {
   type NavGroup,
   type NavPage,
   type NavOpenApiPage,
+  type NavMenu,
   type NavMenuItem,
+  type NavTabItem,
   type NavOpenApi,
   type DocsConfig,
   loadOpenApiSpec,
@@ -22,6 +24,11 @@ import { prependBasePath, withBasePath } from "./base-path";
 import { getCollection } from "astro:content";
 
 type MdxNavPageItem = string | NavPage;
+type NavigationContentContainer = {
+  pages?: (string | NavPage | NavGroup | NavOpenApiPage)[];
+  menu?: NavMenu;
+  openapi?: string | NavOpenApi;
+};
 
 // Base route interface
 export interface BaseRoute {
@@ -420,30 +427,66 @@ async function processMenuItem(
     ? `${parentSlug}/${menuItemSlug}`
     : menuItemSlug;
 
-  const submenu = menuItem.submenu;
+  routes = routes.concat(
+    await processNavigationContent(menuItem, currentPrefix, docs),
+  );
 
-  // Process pages if they exist (pages array can contain pages and groups)
-  if (submenu.pages) {
-    for (const item of submenu.pages) {
-      if (typeof item === "string" || "page" in item) {
-        routes.push(processPageItem(item, currentPrefix, docs));
-      } else if ("group" in item) {
+  return routes;
+}
+
+async function processMenu(
+  menu: NavMenu,
+  parentSlug: string = "",
+  docs: any[],
+): Promise<Route[]> {
+  let routes: Route[] = [];
+
+  for (const menuItem of menu.items) {
+    const menuItemRoutes = await processMenuItem(menuItem, parentSlug, docs);
+    routes = routes.concat(menuItemRoutes);
+  }
+
+  return routes;
+}
+
+async function processTabItem(
+  tabItem: NavTabItem,
+  parentSlug: string = "",
+  docs: any[],
+): Promise<Route[]> {
+  const tabSlug = slugify(tabItem.slug || tabItem.label);
+  const currentPrefix = parentSlug ? `${parentSlug}/${tabSlug}` : tabSlug;
+
+  return processNavigationContent(tabItem, currentPrefix, docs);
+}
+
+async function processNavigationContent(
+  item: NavigationContentContainer,
+  parentSlug: string,
+  docs: any[],
+): Promise<Route[]> {
+  let routes: Route[] = [];
+
+  if (item.pages) {
+    for (const pageItem of item.pages) {
+      if (typeof pageItem === "string" || "page" in pageItem) {
+        routes.push(processPageItem(pageItem, parentSlug, docs));
+      } else if ("group" in pageItem) {
         routes = routes.concat(
-          await processGroup(item as NavGroup, currentPrefix, docs),
+          await processGroup(pageItem as NavGroup, parentSlug, docs),
         );
-      } else if ("openapi" in item) {
-        routes.push(await processOpenApiPageItem(item, currentPrefix));
+      } else if ("openapi" in pageItem) {
+        routes.push(await processOpenApiPageItem(pageItem, parentSlug));
       }
     }
   }
 
-  // Process OpenAPI file if it exists
-  if (submenu.openapi) {
-    const openApiRoutes = await processOpenApiFile(
-      submenu.openapi,
-      currentPrefix,
-    );
-    routes = routes.concat(openApiRoutes);
+  if (item.menu) {
+    routes = routes.concat(await processMenu(item.menu, parentSlug, docs));
+  }
+
+  if (item.openapi) {
+    routes = routes.concat(await processOpenApiFile(item.openapi, parentSlug));
   }
 
   return routes;
@@ -483,7 +526,7 @@ export async function getAllRoutes(): Promise<Route[]> {
 
   let allRoutes: Route[] = [];
 
-  // 3. Identify the active navigation container (pages or menu)
+  // 3. Identify the active navigation container
   // We use the XOR guarantee from validateNavigation (only one key exists)
   if (navigation.pages) {
     // Case 1: Pages array at the top level (can contain pages and groups)
@@ -499,15 +542,14 @@ export async function getAllRoutes(): Promise<Route[]> {
       }
     }
   } else if (navigation.menu) {
-    // Case 3: Menu object at the top level
-    // Need to await all menu items since processMenuItem is now async
-    for (const menuItem of navigation.menu.items) {
-      const menuItemRoutes = await processMenuItem(menuItem, "", docs);
-      allRoutes = allRoutes.concat(menuItemRoutes);
-    }
+    allRoutes = allRoutes.concat(await processMenu(navigation.menu, "", docs));
   } else if (navigation.openapi) {
     const openApiRoutes = await processOpenApiFile(navigation.openapi, "");
     allRoutes = allRoutes.concat(openApiRoutes);
+  } else if (navigation.tabs) {
+    for (const tabItem of navigation.tabs.items) {
+      allRoutes = allRoutes.concat(await processTabItem(tabItem, "", docs));
+    }
   }
 
   for (const auxiliaryPageRef of getAuxiliaryPageRefs(config)) {

package/template/src/styles/global.css

@@ -139,6 +139,18 @@
   display: none !important;
 }
 
+/* Disable route transition animation while preserving Astro client navigation. */
+::view-transition,
+::view-transition-group(*),
+::view-transition-image-pair(*),
+::view-transition-old(*),
+::view-transition-new(*) {
+  animation: none !important;
+  animation-delay: 0s !important;
+  animation-duration: 0s !important;
+  mix-blend-mode: normal !important;
+}
+
 /* Prose styling */
 .prose-rules {
   @apply prose max-w-none *:my-6 *:first:mt-0 *:last:mb-0 prose-h2:mt-12 prose-h2:mb-2 prose-h2:scroll-mt-24 prose-h3:mt-8 prose-h3:mb-2 prose-h3:scroll-mt-20 prose-headings:font-semibold prose-p:mt-0 prose-p:mb-4 prose-ol:mt-0 prose-ol:mb-5 prose-ul:mt-0 prose-ul:mb-5 prose-a:decoration-(--color-theme) prose-a:decoration-from-font prose-blockquote:border-(--color-theme)/30 dark:prose-blockquote:border-(--color-theme)/30;