@specglass/theme-default 0.0.2

package/src/components/ApiNavigation.astro

@@ -0,0 +1,110 @@
+---
+/**
+ * ApiNavigation.astro — Sidebar navigation for API reference endpoints.
+ * Groups endpoints by tag and highlights the current endpoint.
+ */
+import type { ApiEndpoint } from "@specglass/core";
+import { buildEndpointSlug, buildEndpointId } from "@specglass/core";
+
+export interface Props {
+  endpoints: ApiEndpoint[];
+  currentEndpointId: string;
+  basePath: string;
+}
+
+const { endpoints, currentEndpointId, basePath } = Astro.props;
+
+// Group endpoints by tag
+const grouped = new Map<string, ApiEndpoint[]>();
+for (const ep of endpoints) {
+  const tag = ep.tags?.[0] ?? "default";
+  if (!grouped.has(tag)) grouped.set(tag, []);
+  grouped.get(tag)!.push(ep);
+}
+
+const methodBadgeColors: Record<string, string> = {
+  get: "bg-emerald-500/20 text-emerald-700 dark:text-emerald-400",
+  post: "bg-blue-500/20 text-blue-700 dark:text-blue-400",
+  put: "bg-amber-500/20 text-amber-700 dark:text-amber-400",
+  patch: "bg-yellow-500/20 text-yellow-700 dark:text-yellow-400",
+  delete: "bg-red-500/20 text-red-700 dark:text-red-400",
+  options: "bg-purple-500/20 text-purple-700 dark:text-purple-400",
+  head: "bg-gray-500/20 text-gray-700 dark:text-gray-400",
+};
+---
+
+<nav class="api-nav space-y-4" aria-label="API endpoints">
+  {
+    Array.from(grouped.entries()).map(([tag, tagEndpoints]) => (
+      <div>
+        <button
+          class="flex w-full items-center gap-2 text-xs font-semibold text-text-muted uppercase tracking-wider px-3 py-2 hover:text-text transition-colors"
+          aria-expanded="true"
+          data-api-nav-group={tag}
+        >
+          <svg
+            class="h-3 w-3 shrink-0 transition-transform"
+            viewBox="0 0 12 12"
+            fill="currentColor"
+            aria-hidden="true"
+          >
+            <path d="M4.5 2l4 4-4 4" />
+          </svg>
+          {tag}
+        </button>
+        <ul class="ml-3 space-y-0.5" data-api-nav-items={tag}>
+          {tagEndpoints.map((ep) => {
+            const epId = buildEndpointId(ep);
+            const isActive = epId === currentEndpointId;
+            const slug = buildEndpointSlug(ep);
+            const badgeColor = methodBadgeColors[ep.method.toLowerCase()] ?? methodBadgeColors.get;
+
+            return (
+              <li>
+                <a
+                  href={`${basePath}/${slug}`}
+                  class:list={[
+                    "flex items-center gap-2 px-3 py-1.5 rounded-md text-xs transition-colors group",
+                    isActive
+                      ? "bg-primary/10 text-primary font-medium"
+                      : "text-text-muted hover:bg-surface-raised hover:text-text",
+                  ]}
+                  aria-current={isActive ? "page" : undefined}
+                >
+                  <span
+                    class:list={[
+                      "inline-flex w-12 justify-center shrink-0 px-1 py-0.5 rounded text-[10px] font-bold uppercase tracking-wider",
+                      badgeColor,
+                    ]}
+                  >
+                    {ep.method.toUpperCase()}
+                  </span>
+                  <span class="font-mono truncate">{ep.path}</span>
+                </a>
+              </li>
+            );
+          })}
+        </ul>
+      </div>
+    ))
+  }
+</nav>
+
+<script>
+  // Collapsible tag groups
+  document.querySelectorAll<HTMLButtonElement>("[data-api-nav-group]").forEach((btn) => {
+    btn.addEventListener("click", () => {
+      const tag = btn.dataset.apiNavGroup!;
+      const items = document.querySelector(`[data-api-nav-items="${tag}"]`);
+      const arrow = btn.querySelector("svg");
+      if (items) {
+        const isHidden = items.classList.toggle("hidden");
+        btn.setAttribute("aria-expanded", String(!isHidden));
+        arrow?.classList.toggle("rotate-90", !isHidden);
+      }
+    });
+    // Default to expanded
+    const arrow = btn.querySelector("svg");
+    arrow?.classList.add("rotate-90");
+  });
+</script>

package/src/components/ApiParameters.astro

@@ -0,0 +1,204 @@
+---
+/**
+ * ApiParameters.astro — Displays endpoint parameters and request body.
+ * Groups parameters by location (path, query, header, cookie) with type rendering.
+ */
+import type { ApiParameter, ApiRequestBody } from "@specglass/core";
+import { renderTypeString, flattenSchemaProperties } from "../utils/schema-renderer";
+
+export interface Props {
+  parameters: ApiParameter[];
+  requestBody?: ApiRequestBody;
+}
+
+const { parameters, requestBody } = Astro.props;
+
+// Group parameters by location
+const paramGroups: { label: string; key: string; params: ApiParameter[] }[] = [
+  { label: "Path Parameters", key: "path", params: [] },
+  { label: "Query Parameters", key: "query", params: [] },
+  { label: "Header Parameters", key: "header", params: [] },
+  { label: "Cookie Parameters", key: "cookie", params: [] },
+];
+
+for (const param of parameters) {
+  const group = paramGroups.find((g) => g.key === param.in);
+  if (group) {
+    group.params.push(param);
+  }
+}
+
+const nonEmptyGroups = paramGroups.filter((g) => g.params.length > 0);
+const hasParameters = nonEmptyGroups.length > 0;
+const hasRequestBody = !!requestBody;
+
+// Process request body content types
+const requestBodyEntries = requestBody?.content ? Object.entries(requestBody.content) : [];
+---
+
+{
+  (hasParameters || hasRequestBody) && (
+    <div class="mb-8">
+      {/* Parameter groups */}
+      {nonEmptyGroups.map((group) => (
+        <div class="mb-6">
+          <h3 class="text-sm font-semibold text-text-muted uppercase tracking-wider mb-3">
+            {group.label}
+          </h3>
+          <div class="border border-border rounded-lg overflow-hidden">
+            <table class="w-full text-sm">
+              <thead>
+                <tr class="bg-surface-raised border-b border-border">
+                  <th class="text-left px-4 py-2.5 text-text-muted font-medium w-1/4">Name</th>
+                  <th class="text-left px-4 py-2.5 text-text-muted font-medium w-1/5">Type</th>
+                  <th class="text-left px-4 py-2.5 text-text-muted font-medium w-20">Required</th>
+                  <th class="text-left px-4 py-2.5 text-text-muted font-medium">Description</th>
+                </tr>
+              </thead>
+              <tbody class="divide-y divide-border">
+                {group.params.map((param) => (
+                  <tr class="hover:bg-surface-raised/50 transition-colors">
+                    <td class="px-4 py-3">
+                      <code class="text-xs font-mono text-text font-semibold">{param.name}</code>
+                    </td>
+                    <td class="px-4 py-3">
+                      <code class="text-xs font-mono text-text-muted">
+                        {renderTypeString(param.schema)}
+                      </code>
+                      {param.schema?.enum && param.schema.enum.length > 0 && (
+                        <div class="mt-1 flex flex-wrap gap-1">
+                          {param.schema.enum.map((val) => (
+                            <span class="inline-block px-1.5 py-0.5 text-xs rounded bg-surface-raised text-text-muted font-mono">
+                              {String(val)}
+                            </span>
+                          ))}
+                        </div>
+                      )}
+                    </td>
+                    <td class="px-4 py-3">
+                      {param.required ? (
+                        <span class="inline-flex px-2 py-0.5 rounded text-xs font-medium bg-red-500/15 text-red-400 border border-red-500/30">
+                          required
+                        </span>
+                      ) : (
+                        <span class="inline-flex px-2 py-0.5 rounded text-xs font-medium bg-surface-raised text-text-muted">
+                          optional
+                        </span>
+                      )}
+                    </td>
+                    <td class="px-4 py-3 text-text-muted text-xs">
+                      {param.description || "—"}
+                      {param.example !== undefined && (
+                        <div class="mt-1 text-text-muted/60">
+                          Example:{" "}
+                          <code class="text-xs font-mono">{JSON.stringify(param.example)}</code>
+                        </div>
+                      )}
+                    </td>
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          </div>
+        </div>
+      ))}
+
+      {/* Request Body */}
+      {hasRequestBody && (
+        <div class="mb-6">
+          <h3 class="text-sm font-semibold text-text-muted uppercase tracking-wider mb-3">
+            Request Body
+            {requestBody!.required && (
+              <span class="ml-2 inline-flex px-2 py-0.5 rounded text-xs font-medium bg-red-500/15 text-red-400 border border-red-500/30">
+                required
+              </span>
+            )}
+          </h3>
+          {requestBody!.description && (
+            <p class="text-text-muted text-xs mb-3">{requestBody!.description}</p>
+          )}
+
+          {requestBodyEntries.map(([contentType, mediaType]) => {
+            const bodyProperties = flattenSchemaProperties(
+              mediaType.schema,
+              mediaType.schema?.required,
+            );
+            return (
+              <div class="mb-4">
+                <div class="flex items-center gap-2 mb-2">
+                  <span class="text-xs font-mono text-text-muted px-2 py-0.5 rounded bg-surface-raised border border-border">
+                    {contentType}
+                  </span>
+                </div>
+                {bodyProperties.length > 0 ? (
+                  <div class="border border-border rounded-lg overflow-hidden">
+                    <table class="w-full text-sm">
+                      <thead>
+                        <tr class="bg-surface-raised border-b border-border">
+                          <th class="text-left px-4 py-2.5 text-text-muted font-medium w-1/4">
+                            Field
+                          </th>
+                          <th class="text-left px-4 py-2.5 text-text-muted font-medium w-1/5">
+                            Type
+                          </th>
+                          <th class="text-left px-4 py-2.5 text-text-muted font-medium w-20">
+                            Required
+                          </th>
+                          <th class="text-left px-4 py-2.5 text-text-muted font-medium">
+                            Description
+                          </th>
+                        </tr>
+                      </thead>
+                      <tbody class="divide-y divide-border">
+                        {bodyProperties.map((prop) => (
+                          <tr class="hover:bg-surface-raised/50 transition-colors">
+                            <td class:list={["px-4 py-3", prop.depth > 0 && "pl-8"]}>
+                              <code class="text-xs font-mono text-text font-semibold">
+                                {prop.depth > 0 && <span class="text-text-muted/40 mr-1">↳</span>}
+                                {prop.name}
+                              </code>
+                            </td>
+                            <td class="px-4 py-3">
+                              <code class="text-xs font-mono text-text-muted">{prop.type}</code>
+                              {prop.enumValues && prop.enumValues.length > 0 && (
+                                <div class="mt-1 flex flex-wrap gap-1">
+                                  {prop.enumValues.map((val) => (
+                                    <span class="inline-block px-1.5 py-0.5 text-xs rounded bg-surface-raised text-text-muted font-mono">
+                                      {val}
+                                    </span>
+                                  ))}
+                                </div>
+                              )}
+                            </td>
+                            <td class="px-4 py-3">
+                              {prop.required ? (
+                                <span class="inline-flex px-2 py-0.5 rounded text-xs font-medium bg-red-500/15 text-red-400 border border-red-500/30">
+                                  required
+                                </span>
+                              ) : (
+                                <span class="inline-flex px-2 py-0.5 rounded text-xs font-medium bg-surface-raised text-text-muted">
+                                  optional
+                                </span>
+                              )}
+                            </td>
+                            <td class="px-4 py-3 text-text-muted text-xs">
+                              {prop.description || "—"}
+                            </td>
+                          </tr>
+                        ))}
+                      </tbody>
+                    </table>
+                  </div>
+                ) : (
+                  <div class="border border-border rounded-lg p-4 text-text-muted text-xs">
+                    <code class="font-mono">{renderTypeString(mediaType.schema)}</code>
+                  </div>
+                )}
+              </div>
+            );
+          })}
+        </div>
+      )}
+    </div>
+  )
+}

package/src/components/ApiResponse.astro

@@ -0,0 +1,144 @@
+---
+/**
+ * ApiResponse.astro — Displays endpoint response schemas.
+ * Shows status codes with color-coded badges, descriptions, and response body schemas.
+ */
+import type { ApiResponse } from "@specglass/core";
+import { renderTypeString, flattenSchemaProperties } from "../utils/schema-renderer";
+
+export interface Props {
+  responses: ApiResponse[];
+}
+
+const { responses } = Astro.props;
+
+const statusColors: Record<string, string> = {
+  "2": "bg-emerald-500/15 text-emerald-700 dark:text-emerald-400 border-emerald-500/30",
+  "3": "bg-blue-500/15 text-blue-700 dark:text-blue-400 border-blue-500/30",
+  "4": "bg-amber-500/15 text-amber-700 dark:text-amber-400 border-amber-500/30",
+  "5": "bg-red-500/15 text-red-700 dark:text-red-400 border-red-500/30",
+};
+
+function getStatusColor(code: string): string {
+  const firstDigit = code[0];
+  return statusColors[firstDigit] ?? statusColors["2"];
+}
+---
+
+{
+  responses.length > 0 && (
+    <div class="mb-8">
+      <h3 class="text-sm font-semibold text-text-muted uppercase tracking-wider mb-3">Responses</h3>
+      <div class="space-y-4">
+        {responses.map((response) => {
+          const contentEntries = response.content ? Object.entries(response.content) : [];
+          const headerEntries = response.headers ? Object.entries(response.headers) : [];
+
+          return (
+            <div class="border border-border rounded-lg overflow-hidden">
+              {/* Status code header */}
+              <div class="flex items-center gap-3 px-4 py-3 bg-surface-raised border-b border-border">
+                <span
+                  class:list={[
+                    "inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-bold tracking-wider border",
+                    getStatusColor(response.statusCode),
+                  ]}
+                >
+                  {response.statusCode}
+                </span>
+                <span class="text-sm text-text-muted">{response.description}</span>
+              </div>
+
+              {/* Response body schemas */}
+              {contentEntries.map(([contentType, mediaType]) => {
+                const bodyProperties = flattenSchemaProperties(
+                  mediaType.schema,
+                  mediaType.schema?.required,
+                );
+                return (
+                  <div class="px-4 py-3">
+                    <div class="flex items-center gap-2 mb-2">
+                      <span class="text-xs font-mono text-text-muted px-2 py-0.5 rounded bg-surface-raised border border-border">
+                        {contentType}
+                      </span>
+                    </div>
+                    {bodyProperties.length > 0 ? (
+                      <table class="w-full text-sm">
+                        <thead>
+                          <tr class="border-b border-border/50">
+                            <th class="text-left px-3 py-2 text-text-muted font-medium text-xs w-1/4">
+                              Field
+                            </th>
+                            <th class="text-left px-3 py-2 text-text-muted font-medium text-xs w-1/5">
+                              Type
+                            </th>
+                            <th class="text-left px-3 py-2 text-text-muted font-medium text-xs">
+                              Description
+                            </th>
+                          </tr>
+                        </thead>
+                        <tbody class="divide-y divide-border/30">
+                          {bodyProperties.map((prop) => (
+                            <tr>
+                              <td class:list={["px-3 py-2", prop.depth > 0 && "pl-6"]}>
+                                <code class="text-xs font-mono text-text">
+                                  {prop.depth > 0 && <span class="text-text-muted/40 mr-1">↳</span>}
+                                  {prop.name}
+                                </code>
+                              </td>
+                              <td class="px-3 py-2">
+                                <code class="text-xs font-mono text-text-muted">{prop.type}</code>
+                              </td>
+                              <td class="px-3 py-2 text-text-muted text-xs">
+                                {prop.description || "—"}
+                              </td>
+                            </tr>
+                          ))}
+                        </tbody>
+                      </table>
+                    ) : (
+                      <div class="text-text-muted text-xs">
+                        <code class="font-mono">{renderTypeString(mediaType.schema)}</code>
+                      </div>
+                    )}
+                  </div>
+                );
+              })}
+
+              {/* Response headers */}
+              {headerEntries.length > 0 && (
+                <div class="px-4 py-3 border-t border-border/50">
+                  <h4 class="text-xs font-semibold text-text-muted mb-2">Response Headers</h4>
+                  <table class="w-full text-sm">
+                    <tbody class="divide-y divide-border/30">
+                      {headerEntries.map(([headerName, headerParam]) => (
+                        <tr>
+                          <td class="px-3 py-2 w-1/3">
+                            <code class="text-xs font-mono text-text">{headerName}</code>
+                          </td>
+                          <td class="px-3 py-2">
+                            <code class="text-xs font-mono text-text-muted">
+                              {renderTypeString(headerParam.schema)}
+                            </code>
+                          </td>
+                          <td class="px-3 py-2 text-text-muted text-xs">
+                            {headerParam.description || "—"}
+                          </td>
+                        </tr>
+                      ))}
+                    </tbody>
+                  </table>
+                </div>
+              )}
+
+              {/* Empty response */}
+              {contentEntries.length === 0 && headerEntries.length === 0 && (
+                <div class="px-4 py-3 text-text-muted text-xs italic">No response body</div>
+              )}
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  )
+}

package/src/components/Callout.astro

@@ -0,0 +1,54 @@
+---
+/**
+ * Callout component — renders styled callout boxes for documentation.
+ *
+ * Supports types: info, warning, danger, tip — each with distinct
+ * icon, background color, and left border color.
+ *
+ * @example
+ * <Callout type="warning">This is a warning</Callout>
+ * <Callout>This is an info callout (default)</Callout>
+ */
+
+export interface Props {
+  type?: "info" | "warning" | "danger" | "tip";
+}
+
+const { type = "info" } = Astro.props;
+
+const icons: Record<string, string> = {
+  info: "ℹ️",
+  warning: "⚠️",
+  danger: "🚨",
+  tip: "💡",
+};
+
+const icon = icons[type] ?? icons.info;
+
+/**
+ * Tailwind classes per callout type.
+ * Each variant has: background, left-border, and text color.
+ * These are all light values — dark mode auto-remaps via design tokens.
+ */
+const typeClasses: Record<string, string> = {
+  info: "bg-blue-50 border-l-blue-500 text-blue-900 dark:bg-blue-950/40 dark:text-blue-200",
+  warning: "bg-amber-50 border-l-amber-500 text-amber-900 dark:bg-amber-950/40 dark:text-amber-200",
+  danger: "bg-red-50 border-l-red-500 text-red-900 dark:bg-red-950/40 dark:text-red-200",
+  tip: "bg-emerald-50 border-l-emerald-500 text-emerald-900 dark:bg-emerald-950/40 dark:text-emerald-200",
+};
+
+const classes = typeClasses[type] ?? typeClasses.info;
+---
+
+<aside
+  role="note"
+  class:list={[
+    "flex gap-3 px-5 py-4 my-6 border-l-4 rounded-md text-[0.95rem] leading-relaxed",
+    classes,
+  ]}
+>
+  <span class="shrink-0 text-xl leading-relaxed">{icon}</span>
+  <div class="min-w-0 flex-1 [&>p:first-child]:mt-0 [&>p:last-child]:mb-0">
+    <slot />
+  </div>
+</aside>

package/src/components/Card.astro

@@ -0,0 +1,46 @@
+---
+/**
+ * Card component — renders a styled container with optional title, icon, and link.
+ *
+ * @example
+ * <Card title="Getting Started" icon="🚀" href="/docs/getting-started">
+ *   Learn how to set up your project.
+ * </Card>
+ *
+ * <Card title="Configuration">
+ *   Configure your docs site.
+ * </Card>
+ */
+
+export interface Props {
+  title?: string;
+  icon?: string;
+  href?: string;
+}
+
+const { title, icon, href } = Astro.props;
+const Tag = href ? "a" : "div";
+---
+
+<Tag
+  class:list={[
+    "block p-5 my-4 border border-border rounded-lg bg-surface transition-[border-color,box-shadow] duration-150",
+    href &&
+      "no-underline text-inherit cursor-pointer hover:border-primary hover:shadow-sm hover:shadow-primary/10 focus-visible:outline-2 focus-visible:outline-primary focus-visible:outline-offset-2",
+  ]}
+  href={href}
+>
+  {
+    (icon || title) && (
+      <div class="flex items-center gap-2 mb-2">
+        {icon && <span class="text-xl shrink-0">{icon}</span>}
+        {title && <h3 class="m-0 text-base font-semibold text-text">{title}</h3>}
+      </div>
+    )
+  }
+  <div
+    class="text-[0.9375rem] text-text-muted leading-relaxed [&>p:first-child]:mt-0 [&>p:last-child]:mb-0"
+  >
+    <slot />
+  </div>
+</Tag>