radiant-docs 0.1.0

package/template/src/components/TableOfContents.astro

@@ -0,0 +1,480 @@
+---
+import type { MarkdownHeading } from "astro";
+
+interface Props {
+  headings: MarkdownHeading[];
+}
+
+interface GroupedHeading extends MarkdownHeading {
+  sub: MarkdownHeading[];
+}
+
+const { headings } = Astro.props;
+
+// Group depth 3 headings under their preceding depth 2 heading
+const groupedHeadings: GroupedHeading[] = [];
+
+for (const heading of headings) {
+  if (heading.depth === 2) {
+    groupedHeadings.push({ ...heading, sub: [] });
+  } else if (heading.depth === 3) {
+    // If no depth 2 exists yet, create a blank parent
+    if (groupedHeadings.length === 0) {
+      groupedHeadings.push({ depth: 2, text: "", slug: "", sub: [] });
+    }
+    // Add depth 3 to the last depth 2's sub array
+    groupedHeadings[groupedHeadings.length - 1].sub.push(heading);
+  }
+}
+---
+
+<nav
+  class="sticky top-16 text-[14px]/5 py-16 -mt-16"
+  aria-label="Table of Contents"
+  data-slugs={JSON.stringify(headings.map((h) => h.slug))}
+>
+  <div class="text-sm font-medium mb-3">On this page</div>
+  <div class="flex text-neutral-600/90">
+    <svg viewBox="0 0 22 100" width="22px" height="100" class="shrink-0">
+      <path
+        id="toc-bg-path"
+        d=""
+        stroke-width="1.2"
+        vector-effect="non-scaling-stroke"
+        class="stroke-neutral-200"
+        fill="none"
+        stroke-linecap="round"
+        stroke-linejoin="round"></path>
+      <path
+        id="toc-fg-path"
+        d=""
+        stroke-width="1.4"
+        vector-effect="non-scaling-stroke"
+        class="stroke-blue-700/60 transition-[stroke-dasharray] duration-200"
+        fill="none"
+        stroke-linecap="round"
+        stroke-linejoin="round"></path>
+      <g id="toc-circles"></g>
+    </svg>
+    <ol id="toc-list">
+      {
+        groupedHeadings.map((heading) => (
+          <li class="mt-3 first:mt-0">
+            {heading.text && (
+              <a
+                href={`#${heading.slug}`}
+                class="block transition duration-200 hover:text-neutral-900"
+                data-slug={heading.slug}
+              >
+                {heading.text}
+              </a>
+            )}
+            {heading.sub.length > 0 && (
+              <ol class="ml-4">
+                {heading.sub.map((subHeading) => (
+                  <li class:list={["", heading.text ? "mt-3" : "mt-0"]}>
+                    <a
+                      href={`#${subHeading.slug}`}
+                      class="block transition duration-200 hover:text-neutral-900"
+                      data-slug={subHeading.slug}
+                    >
+                      {subHeading.text}
+                    </a>
+                  </li>
+                ))}
+              </ol>
+            )}
+          </li>
+        ))
+      }
+    </ol>
+  </div>
+
+  <script>
+    function initTableOfContents() {
+      const nav = document.querySelector('nav[aria-label="Table of Contents"]');
+      const svg = nav?.querySelector("svg");
+      const ol = nav?.querySelector("#toc-list");
+
+      if (!svg || !ol) return;
+
+      // Check if TOC is visible (not hidden by responsive class)
+      const firstLink = ol.querySelector("a");
+      if (firstLink && firstLink.offsetHeight === 0) {
+        return; // TOC is hidden, skip initialization
+      }
+
+      // Build path and track link positions for progress indicator
+      let path = "";
+      let currentY = 0;
+      const gap = 12; // mt-3 = 12px
+      const linkPositions: Map<string, { pathLengthAtMid: number }> = new Map();
+
+      // First pass: collect all items with their positions
+      interface ItemInfo {
+        x: number;
+        height: number;
+        slug?: string;
+        yStart: number;
+      }
+      const items: ItemInfo[] = [];
+
+      // Iterate through top-level items to collect data
+      ol.querySelectorAll(":scope > li").forEach((li) => {
+        const topLink = li.querySelector(
+          ":scope > a"
+        ) as HTMLAnchorElement | null;
+        const subOl = li.querySelector(":scope > ol");
+
+        // Handle depth-2 heading (only if it has text/link)
+        if (topLink) {
+          const height = topLink.offsetHeight;
+          if (items.length > 0) currentY += gap;
+          items.push({
+            x: 0.5,
+            height,
+            slug: topLink.dataset.slug,
+            yStart: currentY,
+          });
+          currentY += height;
+        }
+
+        // Handle depth-3 subheadings
+        if (subOl) {
+          subOl.querySelectorAll(":scope > li").forEach((subLi) => {
+            const subLink = subLi.querySelector(
+              "a"
+            ) as HTMLAnchorElement | null;
+            if (!subLink) return;
+
+            const height = subLink.offsetHeight;
+            const hasMt0 = subLi.classList.contains("mt-0");
+
+            if (items.length > 0 && !hasMt0) currentY += gap;
+            items.push({
+              x: 12,
+              height,
+              slug: subLink.dataset.slug,
+              yStart: currentY,
+            });
+            currentY += height;
+          });
+        }
+      });
+
+      // Second pass: build path with midpoint start/end, tracking cumulative path length
+      let pathLength = 0;
+      let prevX: number | null = null;
+      let prevY: number | null = null;
+
+      items.forEach((item, index) => {
+        const isFirst = index === 0;
+        const isLast = index === items.length - 1;
+        const midY = item.yStart + item.height / 2;
+
+        if (isFirst) {
+          // Start at midpoint of first item
+          path = `M ${item.x} ${midY} `;
+          prevX = item.x;
+          prevY = midY;
+
+          // Path length at first item's midpoint is 0
+          if (item.slug) {
+            linkPositions.set(item.slug, { pathLengthAtMid: 0 });
+          }
+
+          if (!isLast) {
+            // Draw from midpoint to bottom
+            path += `L ${item.x} ${item.yStart + item.height} `;
+            pathLength += item.height / 2; // vertical segment
+            prevY = item.yStart + item.height;
+          }
+        } else {
+          // Segment from previous position to this item's top
+          const dx = item.x - prevX!;
+          const dy = item.yStart - prevY!;
+          pathLength += Math.sqrt(dx * dx + dy * dy);
+          path += `L ${item.x} ${item.yStart} `;
+          prevX = item.x;
+          prevY = item.yStart;
+
+          if (isLast) {
+            // Draw from top to midpoint
+            const midLength = item.height / 2;
+            pathLength += midLength;
+            path += `L ${item.x} ${midY} `;
+            prevY = midY;
+
+            if (item.slug) {
+              linkPositions.set(item.slug, { pathLengthAtMid: pathLength });
+            }
+          } else {
+            // Middle item: path length at midpoint is current + half height
+            const pathLengthAtMid = pathLength + item.height / 2;
+
+            if (item.slug) {
+              linkPositions.set(item.slug, {
+                pathLengthAtMid: pathLengthAtMid,
+              });
+            }
+
+            // Draw full height
+            path += `L ${item.x} ${item.yStart + item.height} `;
+            pathLength += item.height;
+            prevY = item.yStart + item.height;
+          }
+        }
+      });
+
+      // Create circles at each item's midpoint
+      const circlesGroup = svg.querySelector("#toc-circles");
+      if (circlesGroup) {
+        // Clear existing circles before creating new ones
+        circlesGroup.innerHTML = "";
+        items.forEach((item) => {
+          const midY = item.yStart + item.height / 2;
+          const circle = document.createElementNS(
+            "http://www.w3.org/2000/svg",
+            "circle"
+          );
+          circle.setAttribute("cx", String(item.x));
+          circle.setAttribute("cy", String(midY));
+          circle.setAttribute("r", "2.5");
+          circle.setAttribute("fill", "currentColor");
+          circle.classList.add(
+            "fill-neutral-300",
+            "transition-all",
+            "duration-200"
+          );
+          if (item.slug) {
+            circle.dataset.slug = item.slug;
+          }
+          circlesGroup.appendChild(circle);
+        });
+      }
+
+      const bgPath = svg.querySelector("#toc-bg-path");
+      const fgPath = svg.querySelector("#toc-fg-path") as SVGPathElement | null;
+
+      bgPath?.setAttribute("d", path);
+      fgPath?.setAttribute("d", path);
+
+      svg.setAttribute("height", String(currentY));
+      svg.setAttribute("viewBox", `-3 0 22 ${currentY}`);
+
+      // Get total path length for calculations
+      let totalLength = 0;
+      if (fgPath) {
+        totalLength = fgPath.getTotalLength();
+        // Disable transition during initial setup to prevent flash
+        fgPath.style.transition = "none";
+        // Initially hide the highlight (use same pattern as "0 visible" state)
+        fgPath.setAttribute(
+          "stroke-dasharray",
+          `0 ${totalLength} 0 ${totalLength}`
+        );
+        fgPath.setAttribute("stroke-dashoffset", "0");
+      }
+
+      // Track all visible headings
+      const visibleSlugs = new Set<string>();
+
+      function updateHighlight() {
+        // Find the range of visible headings by path length
+        let minPathLength = Infinity;
+        let maxPathLength = -Infinity;
+
+        visibleSlugs.forEach((slug) => {
+          const pos = linkPositions.get(slug);
+          if (pos) {
+            minPathLength = Math.min(minPathLength, pos.pathLengthAtMid);
+            maxPathLength = Math.max(maxPathLength, pos.pathLengthAtMid);
+          }
+        });
+
+        // Update the SVG highlight
+        if (fgPath) {
+          // Only show line if 2+ items visible (line connects between circles)
+          if (
+            visibleSlugs.size >= 2 &&
+            minPathLength !== Infinity &&
+            minPathLength !== maxPathLength
+          ) {
+            // Calculate the visible segment length along the path
+            const visibleLength = maxPathLength - minPathLength;
+            // Use dasharray pattern: 0 (no initial dash), gap to start, visible length, large gap to hide rest
+            const dasharray = `0 ${minPathLength} ${visibleLength} ${totalLength}`;
+            fgPath.setAttribute("stroke-dasharray", dasharray);
+            fgPath.setAttribute("stroke-dashoffset", "0");
+          } else if (visibleSlugs.size === 1 && minPathLength !== Infinity) {
+            // 1 visible heading: position gap at this item, ready to grow down
+            fgPath.setAttribute(
+              "stroke-dasharray",
+              `0 ${minPathLength} 0 ${totalLength}`
+            );
+            fgPath.setAttribute("stroke-dashoffset", "0");
+          } else {
+            // 0 visible headings: fully hidden
+            fgPath.setAttribute(
+              "stroke-dasharray",
+              `0 ${totalLength} 0 ${totalLength}`
+            );
+            fgPath.setAttribute("stroke-dashoffset", "0");
+          }
+        }
+
+        // Update circle colors based on visibility
+        const circles = circlesGroup?.querySelectorAll("circle");
+        circles?.forEach((circle) => {
+          const slug = (circle as SVGCircleElement).dataset.slug;
+          if (slug && visibleSlugs.has(slug)) {
+            circle.classList.remove("fill-neutral-300");
+            circle.classList.add("fill-blue-700", "delay-100");
+            circle.setAttribute("r", "3");
+          } else {
+            circle.classList.remove("fill-blue-700", "delay-100");
+            circle.classList.add("fill-neutral-300");
+            circle.setAttribute("r", "2.5");
+          }
+        });
+
+        // Update link text colors based on visibility
+        const tocLinks = ol?.querySelectorAll("a[data-slug]");
+        tocLinks?.forEach((link) => {
+          const slug = (link as HTMLAnchorElement).dataset.slug;
+          if (slug && visibleSlugs.has(slug)) {
+            link.classList.add("text-neutral-900");
+          } else {
+            link.classList.remove("text-neutral-900");
+          }
+        });
+      }
+
+      // Intersection Observer to track headings in view
+      const slugs: string[] = JSON.parse(
+        (nav as HTMLElement).dataset.slugs || "[]"
+      );
+      const headings = slugs
+        .map((slug) => document.getElementById(slug))
+        .filter((el): el is HTMLElement => el !== null);
+
+      const headerOffset = 112;
+
+      // Calculate active headings based on scroll position
+      function getActiveHeadings(): Set<string> {
+        const active = new Set<string>();
+
+        // Add all headings currently in viewport
+
+        for (const heading of headings) {
+          const rect = heading.getBoundingClientRect();
+          if (rect.top >= headerOffset && rect.top < window.innerHeight) {
+            active.add(heading.id);
+          }
+        }
+
+        // Add the "current section" - last heading that scrolled above the header
+        // (user is still reading this section's content)
+        let currentSection: string | null = null;
+        for (const heading of headings) {
+          const rect = heading.getBoundingClientRect();
+          if (rect.top <= headerOffset) {
+            currentSection = heading.id;
+          } else {
+            break; // headings are in order, stop once we find one below
+          }
+        }
+        if (currentSection) {
+          active.add(currentSection);
+        }
+
+        return active;
+      }
+
+      const observer = new IntersectionObserver(
+        () => {
+          // Recalculate active headings whenever any heading crosses the threshold
+          const newVisible = getActiveHeadings();
+          visibleSlugs.clear();
+          newVisible.forEach((slug) => visibleSlugs.add(slug));
+          updateHighlight();
+        },
+        {
+          rootMargin: `-${headerOffset}px 0px 0px 0px`,
+          threshold: 0,
+        }
+      );
+
+      headings.forEach((heading) => observer.observe(heading));
+
+      // Set initial state
+      const initialVisible = getActiveHeadings();
+      initialVisible.forEach((slug) => visibleSlugs.add(slug));
+      updateHighlight();
+
+      // Re-enable transition after initial state is set
+      if (fgPath) {
+        // Force a reflow to apply the non-transitioned state first
+        fgPath.getBoundingClientRect();
+        fgPath.style.transition = "";
+      }
+
+      // Also listen to scroll to catch cases where no heading crosses the threshold
+      let scrollTimeout: ReturnType<typeof setTimeout> | null = null;
+      function handleScroll() {
+        // Throttle scroll updates
+        if (scrollTimeout) return;
+        scrollTimeout = setTimeout(() => {
+          scrollTimeout = null;
+          const newVisible = getActiveHeadings();
+          // Only update if the set has changed
+          const hasChanged =
+            newVisible.size !== visibleSlugs.size ||
+            [...newVisible].some((slug) => !visibleSlugs.has(slug));
+          if (hasChanged) {
+            visibleSlugs.clear();
+            newVisible.forEach((slug) => visibleSlugs.add(slug));
+            updateHighlight();
+          }
+        }, 50);
+      }
+
+      window.addEventListener("scroll", handleScroll, { passive: true });
+
+      // Cleanup on navigation
+      document.addEventListener("astro:before-swap", () => {
+        observer.disconnect();
+        window.removeEventListener("scroll", handleScroll);
+        if (scrollTimeout) clearTimeout(scrollTimeout);
+      });
+    }
+
+    // Run on initial load and after Astro navigation
+    initTableOfContents();
+    document.addEventListener("astro:after-swap", initTableOfContents);
+
+    // Re-initialize when TOC becomes visible (responsive breakpoint)
+    const tocNav = document.querySelector(
+      'nav[aria-label="Table of Contents"]'
+    );
+    if (tocNav) {
+      let wasVisible = tocNav.getBoundingClientRect().width > 0;
+      const resizeObserver = new ResizeObserver((entries) => {
+        for (const entry of entries) {
+          const isVisible = entry.contentRect.width > 0;
+          // Only re-init when transitioning from hidden to visible
+          if (isVisible && !wasVisible) {
+            initTableOfContents();
+          }
+          wasVisible = isVisible;
+        }
+      });
+      resizeObserver.observe(tocNav);
+
+      // Cleanup on navigation
+      document.addEventListener("astro:before-swap", () => {
+        resizeObserver.disconnect();
+      });
+    }
+  </script>
+</nav>

package/template/src/components/ThemeSwitcher.astro

@@ -0,0 +1,84 @@
+---
+import { Icon } from "astro-icon/components";
+---
+
+<div
+  x-data="{
+        theme: localStorage.getItem('theme') || 'system',
+        init() {
+            // 1. Initial positioning
+            this.$nextTick(() => this.updateMarker());
+
+            // Watch for changes to the 'theme' state
+            this.$watch('theme', val => {
+                localStorage.setItem('theme', val);
+                this.updateDOM();
+                this.$nextTick(() => this.updateMarker())
+            });
+
+            this.$watch('open', val => {
+                this.$nextTick(() => this.updateMarker())
+            });
+
+            // Listen for System OS changes (sunset/sunrise)
+            window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', () => {
+                if (this.theme === 'system') this.updateDOM();
+            });
+        },
+        updateDOM() {
+            document.documentElement.classList.add('is-switching-theme')
+            const isDark = this.theme === 'dark' || 
+              (this.theme === 'system' && window.matchMedia('(prefers-color-scheme: dark)').matches);
+
+            document.documentElement.classList.toggle('dark', isDark);
+            setTimeout(() => {
+              document.documentElement.classList.remove('is-switching-theme');
+            }, 200);
+        },
+        markerStyle: { left: null, width: null },
+        updateMarker() {
+            // Use the theme name as the ref key
+            const el = this.$refs[this.theme];
+            if (el) {
+                this.markerStyle = {
+                    left: el.offsetLeft + 'px',
+                    width: el.offsetWidth + 'px',
+                };
+            }
+        }
+    }"
+  class="relative flex gap-[3px] p-0.5 bg-neutral-100 dark:bg-neutral-800 rounded-full w-fit inset-shadow-sm text-neutral-500"
+>
+  <div
+    class="anchor-pill absolute top-[3px] bottom-[3px] bg-white dark:bg-neutral-700 rounded-full shadow-sm ease-out z-0 flex items-center justify-center animate-[scaleIn_0.5s_ease-out]"
+    style="left: 3px;"
+    :style="markerStyle.width ? `left: ${markerStyle.left}; width: ${markerStyle.width}` : ''"
+  >
+  </div>
+  <button
+    x-ref="light"
+    @click="theme = 'light'"
+    :class="theme === 'light' ? 'text-neutral-800' : 'text-neutral-500'"
+    class="p-[5px] rounded-full text-sm font-medium transition-all cursor-pointer z-10"
+  >
+    <Icon name="lucide:sun-medium" class="size-[13px]" />
+  </button>
+
+  <button
+    x-ref="dark"
+    @click="theme = 'dark'"
+    :class="theme === 'dark' ? 'text-neutral-300' : 'text-neutral-500'"
+    class="p-[5px] rounded-full text-sm font-medium transition-all cursor-pointer z-10"
+  >
+    <Icon name="lucide:moon" class="size-[13px]" />
+  </button>
+
+  <button
+    x-ref="system"
+    @click="theme = 'system'"
+    :class="theme === 'system' ? 'text-neutral-800 dark:text-neutral-300' : 'text-neutral-500'"
+    class="p-[5px] rounded-full text-sm font-medium transition-all cursor-pointer z-10"
+  >
+    <Icon name="lucide:monitor" class="size-[13px]" />
+  </button>
+</div>

package/template/src/components/endpoint/PlaygroundBar.astro

@@ -0,0 +1,68 @@
+---
+import { Icon } from "astro-icon/components";
+import { methodColors } from "../../lib/utils";
+import type { OpenApiRoute } from "../../lib/routes";
+
+interface Props {
+  route: OpenApiRoute;
+  serverUrl?: string;
+}
+
+const { route, serverUrl } = Astro.props;
+---
+
+<div
+  class="min-w-0 flex items-center gap-[3px] p-[2px] bg-neutral-100/80 inset-shadow-xs rounded-[14px] border border-neutral-200"
+>
+  <div
+    class="min-w-0 flex-1 flex items-center p-[3px] border border-neutral-200 bg-white rounded-xl shadow-xs overflow-hidden"
+  >
+    <span
+      class:list={[
+        "shrink-0 inline-block px-1.5 ml-1 text-sm font-semibold rounded-md uppercase border",
+        methodColors[route.openApiMethod.toLowerCase()] || methodColors.get,
+      ]}
+    >
+      {route.openApiMethod}
+    </span>
+    <code
+      class="group flex-1 mx-2 h-[30px] flex items-center text-[13px] text-neutral-600 min-w-0 relative cursor-pointer"
+      @click="copyPath()"
+      x-data=`{
+                copied: false,
+                path: '${serverUrl ? serverUrl + route.openApiPath : route.openApiPath}',
+                async copyPath() {
+                  try {
+                    await navigator.clipboard.writeText(this.path);
+                    this.copied = true;
+                    setTimeout(() => {
+                      this.copied = false;
+                    }, 2000);
+                  } catch (err) {
+                    console.error('Failed to copy:', err);
+                  }
+                }
+              }`
+    >
+      <span class="truncate min-w-0 flex-1">
+        {route.openApiPath}
+      </span>
+      <div
+        class="absolute right-0 top-1/2 -translate-y-1/2 flex items-center gap-1 text-[12px] px-1.5 py-px bg-white border border-neutral-200 rounded-md duration-200 opacity-0 scale-75 group-hover:scale-100 group-hover:opacity-100 group-hover:duration-200 group-hover:ease-out group-hover:delay-75"
+      >
+        <Icon
+          name="lucide:copy"
+          class="**:stroke-[2.4]"
+          x-bind:class="copied ? 'scale-0 opacity-0 delay-0 duration-100':'duration-150 delay-75'"
+        />
+        <Icon
+          name="lucide:check"
+          class="absolute text-green-700 duration-150 **:stroke-3"
+          x-bind:class="copied ? 'scale-100 opacity-100 delay-75':'scale-0 opacity-0'"
+        />
+        Copy
+      </div>
+    </code>
+    <slot />
+  </div>
+</div>

package/template/src/components/endpoint/PlaygroundButton.astro

@@ -0,0 +1,44 @@
+---
+import { Icon } from "astro-icon/components";
+---
+
+<div x-data="{ open: false }" class="shrink-0 ml-auto">
+  <button
+    x-on:click="open = true"
+    class="m-px flex items-center gap-1.5 px-4 py-[5px] text-sm font-medium rounded-lg bg-neutral-900 text-white/95 hover:text-white shadow-[inset_0_1px_0_rgb(255,255,255,0.3),0_0_0_1px_var(--color-neutral-800)] duration-200 transition-all whitespace-nowrap cursor-pointer relative before:absolute before:inset-0 before:shadow-sm before:rounded-lg before:bg-transparent"
+  >
+    Try it
+    <Icon class="ml-2" name="lucide:square-mouse-pointer" />
+  </button>
+  <div
+    x-show="open"
+    style="display: none"
+    x-on:keydown.escape.prevent.stop="open = false"
+    role="dialog"
+    aria-modal="true"
+    x-id="['modal-title']"
+    :aria-labelledby="$id('modal-title')"
+    class="fixed inset-0 z-50 overflow-y-auto"
+  >
+    <div
+      x-show="open"
+      x-transition.opacity
+      class="fixed z-50 inset-0 bg-neutral-400/40 dark:bg-neutral-950/80 backdrop-blur-[2px]"
+    >
+    </div>
+    <div
+      x-show="open"
+      x-transition
+      x-on:click="open = false"
+      class="relative z-50 flex min-h-screen items-center justify-center p-2 xs:p-4"
+    >
+      <div
+        x-on:click.stop
+        x-trap.noscroll.inert="open"
+        class="relative max-w-7xl w-full rounded-xl bg-white p-4 sm:p-6 shadow-lg"
+      >
+        <slot />
+      </div>
+    </div>
+  </div>
+</div>