radiant-docs 0.1.0

package/template/src/components/OpenApiPage.astro

@@ -0,0 +1,270 @@
+---
+import Layout from "../layouts/Layout.astro";
+import type { OpenApiRoute } from "../lib/routes";
+import { loadOpenApiSpec } from "../lib/validation";
+import RequestSnippets from "./endpoint/RequestSnippets.astro";
+import Oas from "oas";
+import type { HttpMethods } from "oas/types";
+import ResponseSnippets from "./endpoint/ResponseSnippets.astro";
+import { renderMarkdown } from "../lib/utils";
+import Field from "./ui/Field.astro";
+import ResponseFields from "./endpoint/ResponseFields.astro";
+import PlaygroundBar from "./endpoint/PlaygroundBar.astro";
+import PlaygroundForm from "./endpoint/PlaygroundForm.astro";
+import PlaygroundButton from "./endpoint/PlaygroundButton.astro";
+import { getOasInstance } from "../lib/oas";
+
+interface Props {
+  route: OpenApiRoute;
+}
+
+const { route } = Astro.props;
+
+// Load and parse the OpenAPI file (handles both URLs and local files)
+const api = await getOasInstance(route.filePath);
+
+const definition = api.getDefinition();
+const serverUrl = definition.servers?.[0]?.url;
+
+const operation = api.operation(
+  route.openApiPath,
+  route.openApiMethod as HttpMethods
+);
+
+const title = route.title;
+const responses = operation.schema.responses;
+const description = operation.getDescription();
+const formattedDescription = description
+  ? await renderMarkdown(description)
+  : null;
+
+export const headers: { [key: string]: string } = {
+  header: "Header",
+  cookie: "Cookie",
+  path: "Path Parameters",
+  query: "Query Parameters",
+  body: "Body",
+};
+export interface Field {
+  name: string;
+  required: boolean;
+  type: string;
+  description: string;
+  enum?: string[];
+}
+
+export interface RequestFields {
+  header: Field[];
+  cookie: Field[];
+  path: Field[];
+  query: Field[];
+  body: Field[];
+}
+
+const requestFields: RequestFields = {
+  header: [] as Field[],
+  cookie: [] as Field[],
+  path: [] as Field[],
+  query: [] as Field[],
+  body: [] as Field[],
+};
+
+// Authorization
+const securityRequirements = operation.getSecurity();
+const schemes = definition.components?.securitySchemes || {};
+
+if (securityRequirements && securityRequirements.length > 0) {
+  const firstOption = securityRequirements[0];
+
+  Object.keys(firstOption).forEach((key) => {
+    const scheme = schemes[key];
+    if (!scheme) return;
+
+    // Common defaults for all auth types
+    const fieldData: Field = {
+      name: "", // Will be determined below
+      required: true, // If it's in the requirement list, it is required
+      type: "string", // Auth credentials are essentially always strings
+      description: scheme.description || "", // Fallback description logic below
+    };
+
+    // --- CASE 1: API KEY (Explicit Location) ---
+    if (scheme.type === "apiKey") {
+      fieldData.name = scheme.name; // e.g. 'x-api-key' or 'api_token'
+
+      if (!fieldData.description) {
+        fieldData.description = `API Key required in ${scheme.in}.`;
+      }
+
+      // Sort into buckets
+      if (scheme.in === "header") requestFields.header.push(fieldData);
+      else if (scheme.in === "query") requestFields.query.push(fieldData);
+      else if (scheme.in === "cookie") requestFields.cookie.push(fieldData);
+    }
+
+    // --- CASE 2: HTTP (Bearer / Basic) ---
+    // These are implicit headers.
+    else if (scheme.type === "http") {
+      fieldData.name = "Authorization";
+
+      if (scheme.scheme === "bearer") {
+        fieldData.description =
+          fieldData.description || "Bearer token authentication.";
+      } else if (scheme.scheme === "basic") {
+        fieldData.description =
+          fieldData.description ||
+          "Basic authentication (Base64 encoded username:password).";
+      }
+
+      requestFields.header.push(fieldData);
+    }
+
+    // --- CASE 3: OAUTH2 / OPENID ---
+    // Standard practice is a Bearer header.
+    else if (scheme.type === "oauth2" || scheme.type === "openIdConnect") {
+      fieldData.name = "Authorization";
+      fieldData.description = fieldData.description || "OAuth2 Bearer Token.";
+
+      requestFields.header.push(fieldData);
+    }
+  });
+}
+
+// --- Regular Parameters (Path & Query) ---
+const parameters = operation.getParameters();
+parameters.forEach((param) => {
+  const schema = param.schema as any;
+
+  const field = {
+    name: param.name,
+    required: param.required || false,
+    type: schema?.enum
+      ? `enum<${schema?.type || "string"}>`
+      : schema?.type || "string",
+    description: param.description || "",
+    enum: schema?.enum,
+  };
+
+  if (param.in === "path") requestFields.path.push(field);
+  if (param.in === "query") requestFields.query.push(field);
+  if (param.in === "header") requestFields.header.push(field);
+});
+
+// --- 3. Body Parameters ---
+if (operation.hasRequestBody()) {
+  const requestBody = operation.getRequestBody("application/json");
+  const bodySchema = (requestBody as any)?.schema as any;
+
+  // A helper to extract properties (handles direct properties or allOf)
+  let properties = bodySchema?.properties || {};
+  let required: string[] = bodySchema?.required || [];
+
+  if (bodySchema?.allOf) {
+    bodySchema.allOf.forEach((s: any) => {
+      if (s.properties) properties = { ...properties, ...s.properties };
+      if (s.required && Array.isArray(s.required)) {
+        // Merge required arrays from allOf schemas
+        required = [...new Set([...required, ...s.required])];
+      }
+    });
+  }
+
+  Object.entries(properties)
+    .sort(([nameA], [nameB]) => {
+      const aRequired = required.includes(nameA);
+      const bRequired = required.includes(nameB);
+      // Required fields first (aRequired && !bRequired = -1, !aRequired && bRequired = 1, else 0)
+      if (aRequired && !bRequired) return -1;
+      if (!aRequired && bRequired) return 1;
+      return 0;
+    })
+    .forEach(([name, schema]: [string, any]) => {
+      requestFields.body.push({
+        name: name,
+        required: required.includes(name) || false,
+        type: schema?.enum
+          ? `enum<${schema?.type || "string"}>`
+          : schema?.type || "string",
+        description: schema.description || "",
+        enum: schema?.enum,
+      });
+    });
+}
+---
+
+<Layout>
+  <article>
+    <header class="mb-6">
+      <h1 class="text-3xl font-semibold">{title}</h1>
+    </header>
+    <div class="flex flex-row-reverse justify-between gap-6 w-full">
+      <aside class="flex-1 hidden xl:block">
+        <div class="sticky top-[68px] space-y-6 pt-16 -mt-16">
+          <RequestSnippets
+            api={api}
+            method={route.openApiMethod}
+            path={route.openApiPath}
+          />
+          {responses && <ResponseSnippets responses={responses} />}
+        </div>
+      </aside>
+      <div class="flex-1 min-w-0">
+        <div class="mb-8">
+          <PlaygroundBar route={route} serverUrl={serverUrl}>
+            {
+              serverUrl && (
+                <PlaygroundButton>
+                  <PlaygroundForm
+                    serverUrl={serverUrl}
+                    route={route}
+                    requestFields={requestFields}
+                  />
+                </PlaygroundButton>
+              )
+            }
+          </PlaygroundBar>
+        </div>
+        {
+          formattedDescription && (
+            <div class="mb-6 prose-rules" set:html={formattedDescription} />
+          )
+        }
+        <div class="xl:hidden space-y-6 mt-6">
+          <RequestSnippets
+            api={api}
+            method={route.openApiMethod}
+            path={route.openApiPath}
+          />
+          {responses && <ResponseSnippets responses={responses} />}
+        </div>
+        <div class="mt-10">
+          <!-- Request -->
+          {
+            Object.keys(requestFields).map(
+              (key) =>
+                requestFields[key as keyof RequestFields].length > 0 && (
+                  <>
+                    <h4 class="text-xl font-semibold mt-10">{headers[key]}</h4>
+                    <div class="*:mt-4 *:ml-4 *:pb-4 border-b border-b-neutral-100">
+                      {requestFields[key as keyof RequestFields].map((h) => (
+                        <Field
+                          name={h.name}
+                          type={h.type}
+                          required={h.required}
+                          description={h.description}
+                          enum={h.enum}
+                        />
+                      ))}
+                    </div>
+                  </>
+                )
+            )
+          }
+
+          <!-- Response -->
+          {responses && <ResponseFields responses={responses} />}
+        </div>
+      </div>
+    </div>
+  </article>
+</Layout>

package/template/src/components/Search.astro

@@ -0,0 +1,362 @@
+---
+import { Icon } from "astro-icon/components";
+---
+
+<div
+  x-data="searchComponent()"
+  x-on:keydown.escape.window="close()"
+  x-on:keydown.meta.k.window.prevent="open()"
+  x-on:keydown.ctrl.k.window.prevent="open()"
+  class="relative"
+>
+  <!-- Search Trigger Button -->
+  <button
+    x-on:click="open()"
+    class="md:bg-white dark:md:bg-neutral-800 flex items-center gap-2 h-8 md:min-w-64 px-3 py-1.5 -mr-3 xs:mr-0 text-xs text-neutral-500/80 dark:text-neutral-400/80 hover:text-neutral-500 dark:hover:text-neutral-400 md:border border-border rounded-lg cursor-pointer md:shadow-xs md:hover:shadow-sm transition"
+  >
+    <Icon name="lucide:search" class="size-5 md:size-4" />
+    <span class="hidden md:inline">Search documentation</span>
+    <kbd
+      class="font-sans tracking-wider hidden md:inline-flex ml-auto items-center gap-0.5 px-1.5 py-px text-[10px] text-neutral-500 dark:text-neutral-400 font-medium bg-white dark:bg-neutral-700 border border-border/80 rounded"
+    >
+      ⌘K
+    </kbd>
+  </button>
+
+  <!-- Search Modal -->
+  <template x-teleport="body">
+    <div x-show="isOpen" x-cloak class="fixed inset-0 z-50">
+      <!-- Backdrop - NO transitions, just appears/disappears with parent -->
+      <div
+        x-on:click="close()"
+        class="absolute inset-0 bg-neutral-400/40 dark:bg-neutral-950/80 backdrop-blur-[2px]"
+      >
+      </div>
+
+      <!-- Modal Content - this is the only thing that animates -->
+      <div class="relative flex items-start justify-center pt-[15vh] px-4">
+        <div
+          x-show="isOpen"
+          x-transition:enter="transition ease-out duration-150"
+          x-transition:enter-start="opacity-0 scale-95"
+          x-transition:enter-end="opacity-100 scale-100"
+          x-transition:leave="transition ease-in duration-100"
+          x-transition:leave-start="opacity-100 scale-100"
+          x-transition:leave-end="opacity-0 scale-95"
+          x-on:click.outside="close()"
+          class="w-full max-w-xl bg-white dark:bg-neutral-800 rounded-xl shadow-2xl border border-neutral-200 dark:border-neutral-700/80 overflow-hidden"
+        >
+          <!-- Search Input -->
+          <div
+            class="flex items-center gap-3 px-4"
+            :class="{ 'border-b border-neutral-200/80': results.length > 0 || (query.length > 0 && !loading) }"
+          >
+            <Icon
+              name="lucide:search"
+              class="size-5 sm:size-[18px] text-neutral-400 shrink-0"
+            />
+            <input
+              x-ref="searchInput"
+              x-model="query"
+              x-on:input="loading = query.trim().length > 0"
+              x-on:input.debounce.200ms="search()"
+              x-on:keydown.arrow-down.prevent="selectNext()"
+              x-on:keydown.arrow-up.prevent="selectPrevious()"
+              x-on:keydown.enter.prevent="goToSelected()"
+              type="text"
+              placeholder="Search documentation..."
+              class="flex-1 py-4 text-base bg-transparent outline-none placeholder:text-neutral-400 sm:text-sm"
+            />
+            <div x-show="loading" class="shrink-0 p-1">
+              <Icon
+                name="lucide:loader"
+                class="w-4 h-4 text-neutral-400 animate-spin"
+              />
+            </div>
+            <button
+              x-show="query.length > 0 && !loading"
+              x-on:click="clear()"
+              class="shrink-0 p-1 text-neutral-400 hover:text-neutral-600 transition-colors"
+            >
+              <Icon name="lucide:x" class="w-4 h-4" />
+            </button>
+          </div>
+
+          <!-- Results -->
+          <div class="max-h-[60vh] overflow-y-auto">
+            <!-- No Results -->
+            <div
+              x-show="query.length > 0 && results.length === 0 && !loading"
+              class="px-4 py-8 text-center text-neutral-500"
+            >
+              <Icon
+                name="lucide:search-slash"
+                class="size-8 mx-auto mb-3 text-neutral-300"
+              />
+              <p class="text-sm">
+                No results found for <strong class="text-neutral-600"
+                  >"<span x-text="query"></span>"</strong
+                >.
+              </p>
+            </div>
+
+            <!-- Results List -->
+            <ul
+              x-show="results.length > 0"
+              class="divide-y divide-neutral-200/80"
+            >
+              <template
+                x-for="(result, index) in results"
+                :key="result.url + '-' + index"
+              >
+                <li :data-index="index">
+                  <a
+                    :href="result.url"
+                    x-on:click="close()"
+                    x-on:mouseenter="selectedIndex = index"
+                    class="flex flex-col gap-1 px-4 py-3 transition-colors"
+                    :class="{ 'bg-neutral-100/60': selectedIndex === index }"
+                  >
+                    <div class="flex items-center gap-2">
+                      <!-- Page icon -->
+                      <Icon
+                        name="lucide:file"
+                        x-show="result.type === 'page'"
+                        class="w-4 h-4 text-neutral-400 shrink-0"
+                      />
+                      <!-- Heading icon -->
+                      <Icon
+                        name="lucide:hash"
+                        x-show="result.type === 'heading'"
+                        class="w-4 h-4 text-neutral-400 shrink-0"
+                      />
+                      <!-- Content/body text icon -->
+                      <Icon
+                        name="lucide:text"
+                        x-show="result.type === 'content'"
+                        class="w-4 h-4 text-neutral-400 shrink-0"
+                      />
+                      <!-- Parent title breadcrumb -->
+                      <span
+                        class="text-sm text-neutral-500 truncate"
+                        x-show="result.parentTitle"
+                      >
+                        <span x-text="result.parentTitle"></span>
+                        <span class="mx-1">›</span>
+                      </span>
+                      <!-- Title: highlighted for page/heading, plain for content -->
+                      <span
+                        x-show="result.type === 'page' || result.type === 'heading'"
+                        class="font-medium text-neutral-900 truncate [&_mark]:bg-neutral-200 [&_mark]:text-neutral-900 [&_mark]:rounded [&_mark]:px-0.5"
+                        x-html="highlightMatch(result.title, query)"></span>
+                      <span
+                        x-show="result.type === 'content'"
+                        class="font-medium text-neutral-900 truncate"
+                        x-text="result.title"></span>
+                    </div>
+                    <!-- Excerpt: only for content type -->
+                    <p
+                      x-show="result.type === 'content'"
+                      class="text-sm text-neutral-600 line-clamp-2 pl-6 [&_mark]:bg-neutral-200 [&_mark]:text-neutral-900 [&_mark]:rounded [&_mark]:px-0.5"
+                      x-html="result.excerpt"
+                    >
+                    </p>
+                  </a>
+                </li>
+              </template>
+            </ul>
+          </div>
+        </div>
+      </div>
+    </div>
+  </template>
+</div>
+
+<script>
+  import {
+    search as pagefindSearch,
+    type PagefindResultData,
+  } from "../lib/pagefind";
+
+  // Flattened result type for display
+  interface FlatResult {
+    url: string;
+    title: string;
+    parentTitle?: string;
+    excerpt: string;
+    type: "page" | "heading" | "content";
+  }
+
+  document.addEventListener("alpine:init", () => {
+    // @ts-ignore
+    Alpine.data("searchComponent", () => ({
+      isOpen: false,
+      query: "",
+      results: [] as FlatResult[],
+      loading: false,
+      selectedIndex: -1,
+
+      open() {
+        this.isOpen = true;
+        document.body.style.overflow = "hidden";
+        this.$nextTick(() => {
+          (this.$refs.searchInput as HTMLInputElement)?.focus();
+        });
+      },
+
+      close() {
+        this.isOpen = false;
+        document.body.style.overflow = "";
+        this.query = "";
+        this.results = [];
+        this.selectedIndex = -1;
+      },
+
+      clear() {
+        this.query = "";
+        this.results = [];
+        this.selectedIndex = -1;
+        (this.$refs.searchInput as HTMLInputElement)?.focus();
+      },
+
+      selectNext() {
+        if (this.results.length === 0) return;
+        this.selectedIndex = (this.selectedIndex + 1) % this.results.length;
+        this.scrollToSelected();
+      },
+
+      selectPrevious() {
+        if (this.results.length === 0) return;
+        this.selectedIndex =
+          this.selectedIndex <= 0
+            ? this.results.length - 1
+            : this.selectedIndex - 1;
+        this.scrollToSelected();
+      },
+
+      scrollToSelected() {
+        this.$nextTick(() => {
+          const selectedEl = document.querySelector(
+            `[data-index="${this.selectedIndex}"]`
+          );
+          selectedEl?.scrollIntoView({ block: "nearest" });
+        });
+      },
+
+      goToSelected() {
+        if (this.selectedIndex >= 0 && this.results[this.selectedIndex]) {
+          window.location.href = this.results[this.selectedIndex].url;
+        }
+      },
+
+      async search() {
+        if (!this.query.trim()) {
+          this.results = [];
+          this.selectedIndex = -1;
+          return;
+        }
+
+        this.loading = true;
+        this.selectedIndex = -1;
+        try {
+          const rawResults = await pagefindSearch(this.query);
+          const queryLower = this.query.toLowerCase();
+
+          const flatResults: FlatResult[] = [];
+          const seenExcerpts = new Set<string>();
+
+          for (const result of rawResults) {
+            const pageTitle = result.meta?.title || "Untitled";
+            const titleLower = pageTitle.toLowerCase();
+
+            // Use startsWith instead of includes (to match Pagefind's prefix matching)
+            const titleMatchesQuery = titleLower.startsWith(queryLower);
+            const hasSubResults =
+              result.sub_results && result.sub_results.length > 0;
+
+            const matchIsInHeading =
+              hasSubResults &&
+              result.sub_results!.some((sub) =>
+                sub.title.toLowerCase().startsWith(queryLower)
+              );
+
+            // Collect sub-results first (they take priority)
+            const subResultsToAdd: FlatResult[] = [];
+            if (hasSubResults) {
+              for (const sub of result.sub_results!) {
+                // Don't skip same-URL sub_results anymore - they're intro content
+                // if (sub.url === result.url) continue;  // REMOVE THIS LINE
+
+                const subTitleMatches = sub.title
+                  .toLowerCase()
+                  .startsWith(queryLower);
+
+                // Skip if this is intro (same URL) AND title matches the page title
+                // (would be duplicate of main page result)
+                const isIntroSection = sub.url === result.url;
+                if (
+                  isIntroSection &&
+                  sub.title === pageTitle &&
+                  titleMatchesQuery
+                ) {
+                  continue; // Skip only if it would duplicate the page title result
+                }
+
+                subResultsToAdd.push({
+                  url: sub.url,
+                  title: sub.title,
+                  parentTitle: isIntroSection ? undefined : pageTitle, // No parent for intro
+                  excerpt: sub.excerpt,
+                  // Intro content (same URL) or body text = 'content', heading match = 'heading'
+                  type: subTitleMatches ? "heading" : "content",
+                });
+
+                seenExcerpts.add(sub.excerpt);
+              }
+            }
+
+            // Only add main page result if:
+            // 1. Title matches OR match is not in a heading
+            // 2. AND its excerpt isn't already covered by a sub-result
+            if (titleMatchesQuery || !matchIsInHeading) {
+              const excerptAlreadyCovered = seenExcerpts.has(result.excerpt);
+
+              if (!excerptAlreadyCovered) {
+                flatResults.push({
+                  url: result.url,
+                  title: pageTitle,
+                  parentTitle: undefined,
+                  excerpt: result.excerpt,
+                  type: titleMatchesQuery ? "page" : "content",
+                });
+              }
+            }
+
+            // Add the sub-results
+            flatResults.push(...subResultsToAdd);
+          }
+
+          this.results = flatResults;
+
+          if (this.results.length > 0) {
+            this.selectedIndex = 0;
+          }
+        } catch (e) {
+          console.error("Search error:", e);
+          this.results = [];
+        }
+        this.loading = false;
+      },
+
+      // Highlight query matches in a string
+      highlightMatch(text: string, query: string): string {
+        if (!text || !query) return text;
+
+        // Match query only at the start of words (word boundary \b before the match)
+        const escaped = query.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const regex = new RegExp(`\\b(${escaped})`, "gi");
+        return text.replace(regex, "<mark>$1</mark>");
+      },
+    }));
+  });
+</script>

package/template/src/components/Sidebar.astro

@@ -0,0 +1,19 @@
+---
+import { getConfig, type DocsConfig } from "../lib/validation";
+import ThemeSwitcher from "./ThemeSwitcher.astro";
+import SidebarMenu from "./SidebarMenu.astro";
+
+const config: DocsConfig = await getConfig();
+---
+
+<aside class="flex flex-col h-full">
+  <nav class="overflow-y-auto">
+    <SidebarMenu navigation={config.navigation} />
+  </nav>
+  <div
+    class="mt-auto bg-white z-10 p-3 border-t border-t-border-light flex gap-1.5 justify-end items-center"
+  >
+    <span class="text-neutral-400 text-xs font-light">Theme</span>
+    <ThemeSwitcher />
+  </div>
+</aside>