radiant-docs 0.1.0

package/template/src/components/user/Tabs.astro

@@ -0,0 +1,122 @@
+---
+import { Icon } from 'astro-icon/components';
+
+const html = await Astro.slots.render("default");
+
+const labelRegex = /label="([^"]+)"/g;
+const iconRegex = /icon="([^"]*)"/g;
+let labels = [];
+let icons = [];
+let match;
+while ((match = labelRegex.exec(html)) !== null) {
+  labels.push(match[1]);
+}
+while ((match = iconRegex.exec(html)) !== null) {
+  icons.push(match[1]);
+}
+
+if (labels.length === 0) {
+  const pagePath = Astro.url.pathname.replace(/^\/documentation\//, "").replace(/\/$/, "");
+  throw new Error(
+    `[USER_ERROR]: <Tabs>: Must contain at least two <Tab> children (in ${pagePath}.mdx)`
+  );
+}
+
+const tabRegex = /<section[^>]*data-label="[^"]*"[^>]*>(.*?)<\/section>/gs;
+let tabContents = [];
+let contentMatch;
+while ((contentMatch = tabRegex.exec(html)) !== null) {
+  tabContents.push(contentMatch[1]);
+}
+---
+
+<div x-data="{
+  activeTab: 0,
+  containerHeight: 'auto',
+  markerStyle: { left: null, width: null },
+  init() {
+    this.$nextTick(() => {
+      this.updateMarker(this.activeTab);
+      this.updateHeight();
+    });
+    this.$watch('activeTab', (value) => {
+      this.updateMarker(value);
+      this.updateHeight();
+    });
+  },
+  updateMarker(index) {
+    const el = this.$refs['tab-' + index];
+    if (el) {
+      this.markerStyle = {
+        left: el.offsetLeft + 'px',
+        width: el.offsetWidth + 'px',
+      };
+    }
+  },
+  updateHeight() {
+    this.$nextTick(() => {
+      // We look for the internal wrapper or the content div specifically
+      const activeSlide = this.$refs['content-' + this.activeTab];
+      if (activeSlide) {
+        // scrollHeight is often more reliable than offsetHeight for hidden overflow
+        this.containerHeight = activeSlide.scrollHeight + 'px';
+      }
+    });
+  }
+}"
+class="my-5">
+  <ul
+    class="relative isolate not-prose flex border border-neutral-200 w-fit bg-neutral-100/80 rounded-lg p-[3px] inset-shadow-sm"
+  >
+    <div
+      class="absolute top-[3px] bottom-[3px] bg-white rounded-md shadow-sm transition-all duration-300 ease-out -z-10 flex items-center justify-center"
+      style="left: 3px;"
+      :style="markerStyle.width ? `left: ${markerStyle.left}; width: ${markerStyle.width}` : ''"
+    >
+      <span class="px-3 font-medium text-sm opacity-0 select-none" x-show="!markerStyle.width">
+        {labels[0]}
+      </span>
+    </div>
+
+    { labels.map((label, index) => (
+    <li>
+      <button
+        type="button"
+        x-ref={`tab-${index}`}
+        @click={`activeTab = ${index}`}
+        class="relative px-3 h-[32px] font-medium text-sm transition-colors duration-200 cursor-pointer text-nowrap flex items-center gap-2"
+        style={index === 0 ? "" : ""}
+        class:list={[index === 0 ? "text-neutral-900" : "text-neutral-500"]}
+        :class={`{
+        'text-neutral-900': activeTab === ${index},
+        'text-neutral-500 hover:text-neutral-600': activeTab !== ${index}
+      }`}
+      >
+        {icons[index] && <Icon name={`lucide:${icons[index]}`} class="size-4 shrink-0" />}
+        {label}
+      </button>
+    </li>
+    )) }
+  </ul>
+
+  <div 
+    class="mt-4 overflow-hidden transition-[height] duration-300 ease-in-out"
+    :style="'height: ' + containerHeight"
+  >
+    <div 
+      class="flex items-start transition-transform duration-300 ease-in-out"
+      :style="'transform: translateX(-' + (activeTab * 100) + '%)'"
+    >
+    { tabContents.map((content, index) => (
+      // We add a ref here so we can measure the height
+      <div
+        x-ref={`content-${index}`}
+        class="w-full shrink-0 transition-opacity duration-300 ease-in-out"
+        :style={`activeTab === ${index} ? 'opacity: 1' : 'opacity: 0 pointer-events-none'`}
+        style={index === 0 ? 'opacity: 1' : 'opacity: 0'}
+        set:html={content}
+      />
+    )) }
+    </div>
+  </div>
+</div>

package/template/src/content.config.ts

@@ -0,0 +1,11 @@
+import { defineCollection } from "astro:content";
+import { glob } from "astro/loaders";
+import { docsSchema } from "./lib/frontmatter-schema";
+
+const docs = defineCollection({
+  // Load Markdown and MDX files from src/content/docs
+  // This pattern excludes non-content files like docs.json and images
+  loader: glob({ pattern: "**/*.{md,mdx}", base: "./src/content/docs" }),
+});
+
+export const collections = { docs };

package/template/src/entrypoint.ts

@@ -0,0 +1,9 @@
+import collapse from "@alpinejs/collapse";
+import persist from "@alpinejs/persist";
+import focus from "@alpinejs/focus";
+
+export default (Alpine: any) => {
+  Alpine.plugin(collapse);
+  Alpine.plugin(persist);
+  Alpine.plugin(focus);
+};

package/template/src/layouts/Layout.astro

@@ -0,0 +1,92 @@
+---
+import "../styles/global.css";
+import Sidebar from "../components/Sidebar.astro";
+import { getConfig } from "../lib/validation";
+import Header from "../components/Header.astro";
+
+const config = await getConfig();
+---
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <script is:inline>
+      const applyTheme = () => {
+        const localStorageTheme = localStorage.getItem("theme");
+        const systemTheme = window.matchMedia("(prefers-color-scheme: dark)")
+          .matches
+          ? "dark"
+          : "light";
+        const resolvedTheme =
+          localStorageTheme === "system" || !localStorageTheme
+            ? systemTheme
+            : localStorageTheme;
+
+        document.documentElement.classList.toggle(
+          "dark",
+          resolvedTheme === "dark"
+        );
+      };
+
+      // Run on initial load
+      applyTheme();
+    </script>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <meta name="generator" content={Astro.generator} />
+    <title>{config.title} Docs</title>
+  </head>
+  <body
+    class="bg-background text-neutral-900 dark:text-white"
+    x-data="{ open: false }"
+    x-bind:class="open ? 'overflow-hidden touch-none' : ''"
+  >
+    <!-- Edges -->
+    <div class="fixed top-0 inset-x-0 h-16 bg-background-dark -z-10"></div>
+    <div
+      class="fixed top-1 inset-x-1 h-16 bg-background transition-color duration-700 -z-10 rounded-t-xl"
+    >
+    </div>
+    <div class="fixed top-0 inset-x-0 h-1 bg-background-dark z-50"></div>
+    <div
+      class="fixed top-[63px] -z-10 w-[5px] right-0 bottom-0 bg-background-dark border-l border-l-border"
+    >
+    </div>
+    <div
+      class="fixed top-[63px] -z-10 w-[5px] left-0 bottom-0 bg-background-dark border-r border-r-border"
+    >
+    </div>
+    <div
+      class="fixed -z-10 top-1 inset-x-1 bottom-0 rounded-xl shadow-[0_1px_1px_#00000005,0_4px_8px_-4px_#0000000a,0_16px_24px_-8px_#0000000f]"
+    >
+    </div>
+    <!-- Header -->
+    <Header />
+
+    <!-- Desktop Sidebar -->
+    <div
+      class="bg-background w-[283px] ml-[5px] fixed inset-y-0 mt-17 hidden lg:block border-r border-r-border-light"
+      data-pagefind-ignore
+    >
+      <Sidebar />
+    </div>
+
+    <!-- Mobile Menu -->
+    <div
+      x-show="open"
+      x-cloak
+      class="bg-background mx-[5px] min-h-[calc(100vh-68px)] mt-17 fixed inset-0 lg:hidden z-40 overflow-y-auto"
+      x-transition.opacity
+    >
+      <Sidebar />
+    </div>
+
+    <!-- Main Content -->
+    <div class="px-5 sm:px-7 lg:pl-[calc(288px+24px)] pt-16 lg:pr-7">
+      <main class="max-w-2xl xl:max-w-5xl mx-auto pt-16 pb-16">
+        <slot />
+      </main>
+    </div>
+  </body>
+</html>

package/template/src/lib/component-error.ts

@@ -0,0 +1,163 @@
+/**
+ * Component validation utilities for user-facing MDX components.
+ * All errors are tagged with [USER_ERROR] for proper error handling in runner.ts
+ */
+
+/**
+ * Derives the source MDX file path from an Astro URL pathname
+ */
+function getSourceFile(pathname: string): string {
+  const pagePath = pathname
+    .replace(/^\/documentation\//, "") // Remove base path
+    .replace(/\/$/, ""); // Remove trailing slash
+  return `${pagePath}.mdx`;
+}
+
+/**
+ * Formats a user-friendly error message with file location
+ */
+function formatError(
+  componentName: string,
+  message: string,
+  sourceFile: string
+): string {
+  return `[USER_ERROR]: <${componentName}>: ${message} (in ${sourceFile})`;
+}
+
+/**
+ * Validates that a prop value is one of the allowed values
+ *
+ * @example
+ * validateEnum("Callout", "type", type, ["warning", "info", "tip"], Astro.url.pathname);
+ */
+export function validateEnum<T extends string>(
+  componentName: string,
+  propName: string,
+  value: T,
+  validValues: readonly T[],
+  pathname: string
+): void {
+  if (!validValues.includes(value)) {
+    const sourceFile = getSourceFile(pathname);
+    throw new Error(
+      formatError(
+        componentName,
+        `Invalid prop ${propName}="${value}". Expected one of: ${validValues.join(
+          ", "
+        )}`,
+        sourceFile
+      )
+    );
+  }
+}
+
+/**
+ * Validates that a required prop is provided and not empty
+ *
+ * @example
+ * validateRequired("Step", "title", title, Astro.url.pathname);
+ */
+export function validateRequired(
+  componentName: string,
+  propName: string,
+  value: unknown,
+  pathname: string
+): void {
+  if (value === undefined || value === null || value === "") {
+    const sourceFile = getSourceFile(pathname);
+    throw new Error(
+      formatError(
+        componentName,
+        `Missing required prop "${propName}"`,
+        sourceFile
+      )
+    );
+  }
+}
+
+/**
+ * Validates that a prop is of the expected type
+ *
+ * @example
+ * validateType("Accordion", "defaultOpen", defaultOpen, "boolean", Astro.url.pathname);
+ */
+export function validateType(
+  componentName: string,
+  propName: string,
+  value: unknown,
+  expectedType: "string" | "number" | "boolean" | "object" | "array",
+  pathname: string
+): void {
+  // Skip if undefined (optional props)
+  if (value === undefined) return;
+
+  let isValid = false;
+
+  if (expectedType === "array") {
+    isValid = Array.isArray(value);
+  } else {
+    isValid = typeof value === expectedType;
+  }
+
+  if (!isValid) {
+    const sourceFile = getSourceFile(pathname);
+    const actualType = Array.isArray(value) ? "array" : typeof value;
+    throw new Error(
+      formatError(
+        componentName,
+        `Invalid prop "${propName}": expected ${expectedType}, got ${actualType}`,
+        sourceFile
+      )
+    );
+  }
+}
+
+/**
+ * Validates multiple props at once using a schema object
+ *
+ * @example
+ * validateProps("Callout", Astro.props, {
+ *   type: { enum: ["warning", "info", "tip", "danger", "check"] },
+ *   title: { type: "string" },
+ * }, Astro.url.pathname);
+ */
+export type PropSchema = {
+  required?: boolean;
+  type?: "string" | "number" | "boolean" | "object" | "array";
+  enum?: readonly string[];
+};
+
+export function validateProps(
+  componentName: string,
+  props: Record<string, unknown>,
+  schema: Record<string, PropSchema>,
+  pathname: string
+): void {
+  for (const [propName, rules] of Object.entries(schema)) {
+    const value = props[propName];
+
+    // Check required
+    if (rules.required) {
+      validateRequired(componentName, propName, value, pathname);
+    }
+
+    // Skip further checks if value is undefined (optional)
+    if (value === undefined) continue;
+
+    // Check type
+    if (rules.type) {
+      validateType(componentName, propName, value, rules.type, pathname);
+    }
+
+    // Check enum
+    if (rules.enum) {
+      validateEnum(
+        componentName,
+        propName,
+        value as string,
+        rules.enum,
+        pathname
+      );
+    }
+  }
+}

package/template/src/lib/frontmatter-schema.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+
+export const docsSchema = z.object({
+  title: z
+    .string({
+      invalid_type_error: "'title' must be a text string.",
+    })
+    .optional(),
+});

package/template/src/lib/oas.ts

@@ -0,0 +1,24 @@
+import Oas from "oas";
+import { loadOpenApiSpec } from "./validation";
+
+// Cache for dereferenced Oas instances (key: filePathOrUrl, value: Oas instance)
+const oasInstanceCache = new Map<string, Oas>();
+
+export async function getOasInstance(filePathOrUrl: string): Promise<Oas> {
+  // Check cache first
+  if (oasInstanceCache.has(filePathOrUrl)) {
+    return oasInstanceCache.get(filePathOrUrl)!;
+  }
+
+  // Load the spec (uses existing cache)
+  const openApiDoc = await loadOpenApiSpec(filePathOrUrl);
+
+  // Create and dereference Oas instance
+  const api = new Oas(openApiDoc);
+  await api.dereference();
+
+  // Cache the dereferenced instance
+  oasInstanceCache.set(filePathOrUrl, api);
+
+  return api;
+}

package/template/src/lib/pagefind.ts

@@ -0,0 +1,88 @@
+// Pagefind TypeScript types and wrapper
+
+export interface PagefindSearchResult {
+  id: string;
+  data: () => Promise<PagefindResultData>;
+}
+
+export interface PagefindResultData {
+  url: string;
+  content: string;
+  word_count: number;
+  excerpt: string;
+  meta: {
+    title?: string;
+    image?: string;
+    [key: string]: string | undefined;
+  };
+  sub_results?: PagefindSubResult[];
+}
+
+export interface PagefindSubResult {
+  title: string;
+  url: string;
+  excerpt: string;
+}
+
+export interface PagefindSearchResponse {
+  results: PagefindSearchResult[];
+  unfilteredResultCount: number;
+  filters: Record<string, Record<string, number>>;
+  totalFilters: Record<string, Record<string, number>>;
+  timings: {
+    preload: number;
+    search: number;
+    total: number;
+  };
+}
+
+export interface PagefindInstance {
+  init: () => Promise<void>;
+  search: (
+    query: string,
+    options?: { filters?: Record<string, string> }
+  ) => Promise<PagefindSearchResponse>;
+  filters: () => Promise<Record<string, Record<string, number>>>;
+  preload: (query: string) => Promise<void>;
+}
+
+let pagefindInstance: PagefindInstance | null = null;
+
+export async function getPagefind(): Promise<PagefindInstance | null> {
+  if (pagefindInstance) return pagefindInstance;
+
+  try {
+    // Completely bypass Vite's module resolution by constructing the import dynamically
+    // This uses Function constructor to create a truly runtime import
+    const importPagefind = new Function(
+      'return import("/pagefind/pagefind.js")'
+    ) as () => Promise<PagefindInstance>;
+
+    const pagefind = await importPagefind();
+    await pagefind.init();
+    pagefindInstance = pagefind;
+    return pagefindInstance;
+  } catch (e) {
+    console.warn("Pagefind not available:", e);
+    return null;
+  }
+}
+
+export async function search(
+  query: string,
+  limit: number = 8
+): Promise<PagefindResultData[]> {
+  const pagefind = await getPagefind();
+  if (!pagefind || !query.trim()) return [];
+
+  const response = await pagefind.search(query);
+
+  // Load full data for top results
+  const results = await Promise.all(
+    response.results.slice(0, limit).map((result) => result.data())
+  );
+
+  console.log("results", results);
+
+  return results;
+}