radiant-docs 0.1.0

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

@@ -0,0 +1,177 @@
+---
+import { Icon } from "astro-icon/components";
+---
+
+<div
+  x-data={`{
+    selected: 'body',
+    select(value) {
+      this.selected = value;
+      this.$refs.button?.focus();
+      this.close();
+    },
+    close(focusAfter) {
+      if (!this.open) return;
+      this.open = false;
+      focusAfter?.focus();
+    }
+  }`}
+  class="bg-neutral-100 rounded-[14px] border border-neutral-200 p-[3px] inset-shadow-xs"
+  x-bind:class="loading && 'animate-loading'"
+>
+  <div class="flex justify-between items-center">
+    <div
+      class="flex-1 min-w-0 flex items-center font-medium ml-2 text-neutral-700 text-sm"
+    >
+      <span
+        class:list={[
+          "shrink-0 text-xs uppercase font-semibold px-1.5 border py-px rounded-md mr-1.5",
+        ]}
+        x-bind:class="{
+            'bg-green-50 text-green-700/70 border-green-700/10': Math.floor(response?.status / 100) === 2,
+            'bg-blue-50 text-blue-700/70 border-blue-700/10': Math.floor(response?.status / 100) === 3,
+            'bg-amber-50 text-amber-600/80 border-amber-700/10': Math.floor(response?.status / 100) === 4,
+            'bg-red-50 text-red-700/70 border-red-700/10': Math.floor(response?.status / 100) === 5
+          }"
+        x-text="response?.status"
+        x-show="response?.status"></span>
+      <span class="truncate" x-text="response?.statusText"></span>
+    </div>
+    <div
+      x-data="{
+    open: false,
+    toggle() {
+        if (this.open) {
+            return this.close()
+        }
+
+        this.$refs.button.focus()
+
+        this.open = true
+    },
+    close(focusAfter) {
+        if (! this.open) return
+
+        this.open = false
+
+        focusAfter && focusAfter.focus()
+    }
+}"
+      x-on:keydown.escape.prevent.stop="close($refs.button)"
+      x-on:focusin.window="! $refs.panel.contains($event.target) && close()"
+      x-id="['dropdown-button']"
+      class="shrink-0 relative max-w-24 w-full"
+    >
+      <button
+        x-ref="button"
+        x-on:click="toggle()"
+        :aria-expanded="open"
+        :aria-controls="$id('dropdown-button')"
+        type="button"
+        class="flex items-center justify-between px-3 pt-2 pb-1.5 relative border-x border-t border-neutral-200 rounded-t-xl w-full text-sm font-medium bg-white shadow-xs cursor-pointer after:absolute after:-bottom-[2px] after:inset-x-0 after:z-50 after:h-[3px] after:bg-white"
+      >
+        <span class="flex items-center gap-2">
+          <span x-text="selected" class="capitalize"></span>
+        </span>
+        <Icon name="lucide:chevrons-up-down" />
+      </button>
+      <!-- Panel -->
+      <ul
+        x-ref="panel"
+        x-show="open"
+        x-transition.origin.top.left
+        x-on:click.outside="close($refs.button)"
+        :id="$id('dropdown-button')"
+        x-cloak
+        role="menu"
+        class="absolute top-full right-2 min-w-28 rounded-lg shadow-xl mt-2 z-10 origin-top-right bg-white py-0.5 outline-none border border-neutral-200"
+      >
+        <li role="menuitem">
+          <button
+            x-on:click="select('header')"
+            type="button"
+            class="w-full text-left px-3 py-2 text-sm text-neutral-700 rounded-md transition-colors flex items-center gap-2 relative before:absolute before:inset-x-1 before:inset-y-0.5 before:-z-10 before:rounded-md before:duration-150 cursor-pointer"
+            x-bind:class="selected === 'header' ? 'before:bg-neutral-200/50 text-neutral-900' : 'hover:before:bg-neutral-100/70'"
+          >
+            Header
+          </button>
+        </li>
+        <li role="menuitem">
+          <button
+            x-on:click="select('body')"
+            type="button"
+            class="w-full text-left px-3 py-2 text-sm text-neutral-700 rounded-md transition-colors flex items-center gap-2 relative before:absolute before:inset-x-1 before:inset-y-0.5 before:-z-10 before:rounded-md before:duration-150 cursor-pointer"
+            x-bind:class="selected === 'body' ? 'before:bg-neutral-200/50 text-neutral-900' : 'hover:before:bg-neutral-100/70'"
+          >
+            Body
+          </button>
+        </li>
+      </ul>
+    </div>
+  </div>
+  <div
+    class="bg-white border border-neutral-200 rounded-xl rounded-tr-none shadow-xs transition duration-300"
+  >
+    <div x-bind:class="loading && 'opacity-60 duration-700'">
+      <div x-show="selected === 'body'">
+        <div
+          x-show="!response || !response.highlightedData"
+          class="text-sm px-4 py-4 xs:py-8 flex flex-col items-center justify-center"
+        >
+          <div class="bg-neutral-50 p-2 rounded-xl mb-1">
+            <Icon
+              class="size-6 text-neutral-300"
+              name="lucide:square-arrow-up-right"
+            />
+          </div>
+          <div class="text-lg text-center text-neutral-700">Send request</div>
+          <p class="text-sm text-neutral-500 text-center">
+            Send a request to see the response body.
+          </p>
+        </div>
+        <div x-show="response && response.highlightedData">
+          <pre
+            class="bg-transparent! m-0!"><code class="language-json text-[13px]! font-mono! text-neutral-700!" x-html="response?.highlightedData" /></pre>
+        </div>
+      </div>
+      <div x-show="selected === 'header'">
+        <div
+          x-show="!response || !response.headers || Object.keys(response.headers).length === 0"
+          class="text-sm px-4 py-4 xs:py-8 flex flex-col items-center justify-center"
+        >
+          <div class="bg-neutral-50 p-2 rounded-xl mb-1">
+            <Icon
+              class="size-6 text-neutral-300"
+              name="lucide:square-arrow-up-right"
+            />
+          </div>
+          <div class="text-lg text-center text-neutral-700">Send request</div>
+          <p class="text-sm text-neutral-500 text-center">
+            Send a request to see the response header.
+          </p>
+        </div>
+        <div
+          x-show="response && response.headers && Object.keys(response.headers).length > 0"
+          class=""
+        >
+          <table class="w-full border-collapse text-xs table-fixed">
+            <tbody>
+              <template x-for="(value, key) in response?.headers" :key="key">
+                <tr
+                  class="flex border-b last:border-b-0 divide-x divide-neutral-100 border-neutral-100 hover:bg-neutral-50/50"
+                >
+                  <td
+                    class="py-2 px-3 basis-1/2 font-mono font-medium text-neutral-700 overflow-x-auto whitespace-nowrap"
+                    x-text="key"></td>
+                  <td
+                    class="py-2 px-3 basis-1/2 font-mono text-neutral-600 overflow-x-auto whitespace-nowrap"
+                    x-text="value"></td>
+                </tr>
+              </template>
+            </tbody>
+          </table>
+        </div>
+      </div>
+    </div>
+  </div>
+</div>

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

@@ -0,0 +1,224 @@
+---
+import type { OpenAPIV3, OpenAPIV3_1 } from "openapi-types";
+import Field from "../ui/Field.astro";
+
+interface Props {
+  responses: OpenAPIV3.ResponsesObject | OpenAPIV3_1.ResponsesObject;
+}
+
+const { responses } = Astro.props;
+
+interface ResponseField {
+  name: string;
+  required: boolean;
+  type: string;
+  description: string;
+  nested?: ResponseField[]; // For nested objects
+  enum?: string[];
+}
+
+interface ResponseData {
+  statusCode: string;
+  description?: string;
+  fields: ResponseField[];
+}
+
+// Helper function to extract fields from a schema recursively
+function extractFieldsFromSchema(
+  schema: any,
+  parentName: string = "",
+  required: string[] = []
+): ResponseField[] {
+  if (!schema) return [];
+
+  const fields: ResponseField[] = [];
+
+  // Handle allOf - merge properties and required arrays
+  let properties = schema.properties || {};
+  let schemaRequired = schema.required || [];
+
+  if (schema.allOf) {
+    schema.allOf.forEach((s: any) => {
+      if (s.properties) {
+        properties = { ...properties, ...s.properties };
+      }
+      if (s.required && Array.isArray(s.required)) {
+        schemaRequired = [...new Set([...schemaRequired, ...s.required])];
+      }
+    });
+  }
+
+  // Handle array types - extract fields from items
+  if (schema.type === "array" && schema.items) {
+    const itemFields = extractFieldsFromSchema(
+      schema.items,
+      "",
+      schema.items.required || []
+    );
+    if (itemFields.length > 0) {
+      fields.push({
+        name: parentName || "items",
+        required: required.includes(parentName) || false,
+        type: "array",
+        description: schema.description || "",
+        nested: itemFields,
+      });
+    }
+    return fields;
+  }
+  // Extract object properties
+  if (properties && Object.keys(properties).length > 0) {
+    Object.entries(properties)
+      .sort(([nameA], [nameB]) => {
+        const aRequired = schemaRequired.includes(nameA);
+        const bRequired = schemaRequired.includes(nameB);
+        if (aRequired && !bRequired) return -1;
+        if (!aRequired && bRequired) return 1;
+        return 0;
+      })
+      .forEach(([name, propSchema]: [string, any]) => {
+        const fullName = parentName ? `${parentName}.${name}` : name;
+        const isRequired = schemaRequired.includes(name);
+
+        // Determine type
+        let type = propSchema.type || "object";
+        if (propSchema.format) {
+          type = `${type} (${propSchema.format})`;
+        } else if (propSchema.enum) {
+          type = `enum<${propSchema.type || "string"}>`;
+        }
+
+        // Handle nested objects
+        if (
+          propSchema.type === "object" ||
+          propSchema.properties ||
+          propSchema.allOf
+        ) {
+          const nestedFields = extractFieldsFromSchema(
+            propSchema,
+            fullName,
+            propSchema.required || []
+          );
+          fields.push({
+            name: fullName,
+            required: isRequired,
+            type: type,
+            description: propSchema.description || "",
+            nested: nestedFields.length > 0 ? nestedFields : undefined,
+            enum: propSchema.enum,
+          });
+        }
+        // Handle arrays
+        else if (propSchema.type === "array" && propSchema.items) {
+          const itemFields = extractFieldsFromSchema(
+            propSchema.items,
+            `${fullName}[]`,
+            propSchema.items.required || []
+          );
+          fields.push({
+            name: fullName,
+            required: isRequired,
+            type: propSchema.items?.enum
+              ? `enum<${propSchema.items?.type || "object"}>[]`
+              : `${propSchema.items.type || "object"}[]`,
+            description: propSchema.description || "",
+            nested: itemFields.length > 0 ? itemFields : undefined,
+            enum: propSchema.items?.enum,
+          });
+        }
+        // Handle primitive types
+        else {
+          fields.push({
+            name: fullName,
+            required: isRequired,
+            type: type,
+            description: propSchema.description || "",
+            enum: propSchema.enum,
+          });
+        }
+      });
+  }
+
+  return fields;
+}
+
+// Process all responses
+const responseFields: ResponseData[] = [];
+
+Object.entries(responses)
+  .sort(([codeA], [codeB]) => {
+    // Sort by status code: 2xx, 3xx, 4xx, 5xx, then by numeric value
+    const numA = parseInt(codeA) || 0;
+    const numB = parseInt(codeB) || 0;
+    const categoryA = Math.floor(numA / 100);
+    const categoryB = Math.floor(numB / 100);
+
+    if (categoryA !== categoryB) {
+      return categoryA - categoryB;
+    }
+    return numA - numB;
+  })
+  .forEach(([statusCode, response]: [string, any]) => {
+    // Try to get application/json content first
+    const contentType = response.content?.["application/json"]
+      ? "application/json"
+      : Object.keys(response.content || {})[0];
+
+    const mediaType = contentType ? response.content?.[contentType] : null;
+    const schema = mediaType?.schema;
+
+    const fields: ResponseField[] = schema
+      ? extractFieldsFromSchema(schema, "", schema.required || [])
+      : [];
+
+    responseFields.push({
+      statusCode,
+      description: response.description,
+      fields,
+    });
+  });
+---
+
+<div>
+  <h4 class="text-xl font-semibold mt-10">Responses</h4>
+  {
+    responseFields.map((response) => (
+      <div class="mt-6">
+        <div class="flex items-center gap-2 mb-4">
+          <h5 class="text-lg font-medium">{response.statusCode}</h5>
+          {response.description && (
+            <span class="text-sm text-neutral-600">{response.description}</span>
+          )}
+        </div>
+        {response.fields.length > 0 ? (
+          <div class="ml-2 space-y-4">
+            {response.fields.map((field) => (
+              <div>
+                <Field
+                  name={field.name}
+                  type={field.type}
+                  optional={!field.required}
+                  description={field.description}
+                />
+                {field.nested && field.nested.length > 0 && (
+                  <div class="ml-6 mt-2 space-y-2">
+                    {field.nested.map((nestedField) => (
+                      <Field
+                        name={nestedField.name}
+                        type={nestedField.type}
+                        optional={!nestedField.required}
+                        description={nestedField.description}
+                      />
+                    ))}
+                  </div>
+                )}
+              </div>
+            ))}
+          </div>
+        ) : (
+          <p class="text-sm text-neutral-500 ml-2">No response body fields</p>
+        )}
+      </div>
+    ))
+  }
+</div>

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

@@ -0,0 +1,247 @@
+---
+import * as Sampler from "openapi-sampler";
+import type { JSONSchema7 } from "json-schema";
+import type { OpenAPIV3, OpenAPIV3_1 } from "openapi-types";
+import { Icon } from "astro-icon/components";
+import { Code } from "astro-expressive-code/components";
+
+interface Props {
+  responses: OpenAPIV3.ResponsesObject | OpenAPIV3_1.ResponsesObject;
+}
+
+const { responses } = Astro.props;
+
+// Extract and sample response data
+const responseData: Array<{
+  statusCode: string;
+  description?: string;
+  example?: any;
+  contentType?: string;
+}> = [];
+
+Object.entries(responses).forEach(([statusCode, response]: [string, any]) => {
+  // Try to get application/json content first, fallback to first available content type
+  const contentTypes = Object.keys(response.content || {});
+  const contentType = response.content?.["application/json"]
+    ? "application/json"
+    : contentTypes[0];
+
+  const mediaType = contentType ? response.content?.[contentType] : null;
+  const schema = mediaType?.schema;
+
+  let example: any = undefined;
+  if (schema) {
+    try {
+      example = Sampler.sample(schema as JSONSchema7, {
+        skipReadOnly: false,
+      });
+    } catch (err) {
+      console.error(`Failed to sample response ${statusCode}:`, err);
+    }
+  }
+
+  responseData.push({
+    statusCode,
+    description: response.description,
+    example,
+    contentType,
+  });
+});
+
+const statusCodeStyles = {
+  "2": {
+    badge: "bg-green-50 text-green-700/70 border-green-700/10",
+    dot: "bg-green-700/70",
+  },
+  "3": {
+    badge: "bg-blue-50 text-blue-700/70 border-blue-700/10",
+    dot: "bg-blue-700/70",
+  },
+  "4": {
+    badge: "bg-amber-50 text-amber-600/80 border-amber-700/10",
+    dot: "bg-amber-600/80",
+  },
+  "5": {
+    badge: "bg-red-50 text-red-700/70 border-red-700/10",
+    dot: "bg-red-700/70",
+  },
+};
+
+const getStatusCodeClasses = (statusCode: string, type: "badge" | "dot") => {
+  const firstChar = statusCode[0];
+  return (
+    statusCodeStyles[firstChar as keyof typeof statusCodeStyles]?.[type] || ""
+  );
+};
+
+const initialStatusCodeClasses = responseData[0]
+  ? getStatusCodeClasses(responseData[0].statusCode, "badge")
+  : "";
+const initialStatusCodeDotClasses = responseData[0]
+  ? getStatusCodeClasses(responseData[0].statusCode, "dot")
+  : "";
+---
+
+<div
+  x-data={`{
+    responses: ${JSON.stringify(responseData)},
+    selected: 0,
+    select(index) {
+      this.selected = index;
+      this.$refs.button?.focus();
+      this.close();
+    },
+    close(focusAfter) {
+      if (!this.open) return;
+      this.open = false;
+      focusAfter?.focus();
+    }
+  }`}
+  class="response-code-snippets bg-neutral-100 rounded-[14px] border border-neutral-200 shadow-xs. p-[3px] shadow-[inset_0px_0.5px_2px_2px_rgba(0,0,0,0.01)]. inset-shadow-xs"
+>
+  <div class="flex justify-between items-center">
+    <div
+      class="flex-1 min-w-0 flex items-center font-medium ml-2 text-neutral-700 text-sm"
+    >
+      <span
+        class:list={[
+          "shrink-0 text-xs uppercase font-semibold px-1.5 border py-px rounded-md mr-1.5",
+          initialStatusCodeClasses,
+        ]}
+        x-bind:class="{
+            'bg-green-50 text-green-700/70 border-green-700/10': responses[selected].statusCode[0] === '2',
+            'bg-blue-50 text-blue-700/70 border-blue-700/10': responses[selected].statusCode[0] === '3',
+            'bg-amber-50 text-amber-600/80 border-amber-700/10': responses[selected].statusCode[0] === '4',
+            'bg-red-50 text-red-700/70 border-red-700/10': responses[selected].statusCode[0] === '5'
+          }"
+        x-text="responses[selected].statusCode"
+        set:html={responseData[0].statusCode}
+      />
+      <span
+        class="truncate"
+        x-text="responses[selected].description"
+        set:html={responseData[0].description}
+      />
+    </div>
+    <div
+      x-data="{
+    open: false,
+    toggle() {
+        if (this.open) {
+            return this.close()
+        }
+
+        this.$refs.button.focus()
+
+        this.open = true
+    },
+    close(focusAfter) {
+        if (! this.open) return
+
+        this.open = false
+
+        focusAfter && focusAfter.focus()
+    }
+}"
+      x-on:keydown.escape.prevent.stop="close($refs.button)"
+      x-on:focusin.window="! $refs.panel.contains($event.target) && close()"
+      x-id="['dropdown-button']"
+      class="shrink-0 relative max-w-24 w-full"
+    >
+      <button
+        x-ref="button"
+        x-on:click="toggle()"
+        :aria-expanded="open"
+        :aria-controls="$id('dropdown-button')"
+        type="button"
+        class="flex items-center justify-between px-3 pt-2 pb-1.5 relative border-x border-t border-neutral-200/70 rounded-t-xl w-full text-sm font-medium bg-white shadow-[-1px_0px_2px_0px_rgba(0,0,0,0.01)]. shadow-sm cursor-pointer after:absolute after:-bottom-[1.5px] after:inset-x-0 after:z-10 after:h-[3px] after:bg-white"
+      >
+        <span class="flex items-center gap-2">
+          <span
+            class:list={["size-1.5 rounded-full", initialStatusCodeDotClasses]}
+            x-bind:class="{
+            'bg-green-700/70': responses[selected].statusCode[0] === '2',
+            'bg-blue-700/70': responses[selected].statusCode[0] === '3',
+            'bg-amber-600/80': responses[selected].statusCode[0] === '4',
+            'bg-red-700/70': responses[selected].statusCode[0] === '5'
+          }"
+          ></span>
+          <span
+            x-text="responses[selected].statusCode"
+            set:html={responseData[0].statusCode}
+          />
+        </span>
+        <Icon name="lucide:chevrons-up-down" class="ml-auto." />
+      </button>
+      <!-- Panel -->
+      <ul
+        x-ref="panel"
+        x-show="open"
+        x-transition.origin.top.left
+        x-on:click.outside="close($refs.button)"
+        :id="$id('dropdown-button')"
+        x-cloak
+        role="menu"
+        class="absolute top-full right-2 min-w-28 rounded-lg shadow-xl mt-2 z-10 origin-top-right bg-white py-0.5 outline-none border border-neutral-200"
+      >
+        <template
+          x-for="(response, index) in responses"
+          :key="response.statusCode"
+        >
+          <li role="menuitem">
+            <button
+              x-on:click="select(index)"
+              type="button"
+              class="w-full text-left px-3 py-2 text-sm text-neutral-700 rounded-md transition-colors flex items-center gap-2 relative before:absolute before:inset-x-1 before:inset-y-0.5 before:-z-10 before:rounded-md before:duration-150 cursor-pointer"
+              x-bind:class="index === selected ? 'before:bg-neutral-200/50 text-neutral-900' : 'hover:before:bg-neutral-100/70'"
+            >
+              <span
+                class="size-1.5 rounded-full"
+                x-bind:class="{
+                'bg-green-700/70': response.statusCode[0] === '2',
+                'bg-blue-700/70': response.statusCode[0] === '3',
+                'bg-amber-600/80': response.statusCode[0] === '4',
+                'bg-red-700/70': response.statusCode[0] === '5'
+              }"
+              >
+              </span>
+              <span x-text="response.statusCode"></span>
+            </button>
+          </li>
+        </template>
+      </ul>
+    </div>
+  </div>
+  {
+    responseData.map((response, index) => (
+      <div
+        {...(index !== 0 ? { "x-cloak": true } : {})}
+        x-show={`selected === ${index}`}
+        data-snippet-index={index}
+      >
+        <Code
+          code={
+            JSON.stringify(response.example, null, 2) ||
+            "This response has no body data."
+          }
+          lang="json"
+          frame="code"
+        />
+      </div>
+    ))
+  }
+</div>
+
+<style>
+  @reference "../../styles/global.css";
+  :global(.response-code-snippets .expressive-code .frame) {
+    @apply shadow-sm rounded-2xl!;
+  }
+  :global(.response-code-snippets .expressive-code pre) {
+    @apply rounded-xl! rounded-tr-none! border-neutral-200/70!;
+  }
+
+  :global(.response-code-snippets .expressive-code pre code) {
+    @apply max-h-64 overflow-y-auto;
+  }
+</style>

package/template/src/components/sidebar/SidebarEndpointLink.astro

@@ -0,0 +1,51 @@
+---
+import { slugify } from "../../lib/utils";
+import { methodColors } from "../../lib/utils";
+
+interface Props {
+  method: string;
+  path: string;
+  summary?: string;
+  parentSlug?: string;
+}
+
+const { method, path: pathStr, summary, parentSlug = "" } = Astro.props;
+
+// Generate slug from path and method (matching routes.ts logic)
+const pathSlug = pathStr
+  .replace(/^\//, "") // Remove leading slash
+  .replace(/\//g, "-") // Replace slashes with hyphens
+  .replace(/\{[^}]+\}/g, "param"); // Replace path params like {id} with "param"
+
+const methodSlug = slugify(method);
+const endpointSlug = pathSlug ? `${pathSlug}-${methodSlug}` : methodSlug;
+const href = parentSlug ? `/${parentSlug}/${endpointSlug}` : `/${endpointSlug}`;
+
+// Use summary for title, fallback to method + path
+const text = summary || pathStr;
+
+// Normalize paths for comparison (remove trailing slashes)
+const currentPath = Astro.url.pathname.replace(/\/$/, "");
+const targetPath = href.replace(/\/$/, "");
+const isActive = currentPath === targetPath;
+---
+
+<a
+  href={href}
+  class:list={[
+    "flex items-center px-2 py-[7px] text-sm relative z-0 font-[450] before:-z-10 before:absolute before:inset-x-0 before:inset-y-px before:rounded-md before:duration-150",
+    isActive
+      ? "before:bg-neutral-200/50 dark:before:bg-neutral-800 text-neutral-900 dark:text-neutral-200"
+      : "text-neutral-600 dark:text-neutral-400 hover:before:bg-neutral-100/70 dark:hover:before:bg-neutral-800/50 hover:text-neutral-900 dark:hover:text-neutral-300",
+  ]}
+>
+  <span
+    class:list={[
+      "px-1 py-px mr-1.5 border rounded-md text-[10px] font-semibold uppercase",
+      methodColors[method],
+    ]}
+  >
+    {method.toLowerCase() !== "delete" ? method : "del"}
+  </span>
+  {text}
+</a>