specra 0.2.7 → 0.2.8

package/config/svelte-config.js

@@ -17,6 +17,8 @@ import remarkMath from 'remark-math'
 import rehypeSlug from 'rehype-slug'
 import rehypeKatex from 'rehype-katex'
 import rehypeRaw from 'rehype-raw'
+import fs from 'fs'
+import path from 'path'
 
 /**
  * Get mdsvex preprocessor config with all Specra remark/rehype plugins
@@ -42,11 +44,33 @@ export function specraMdsvexConfig(options = {}) {
   }
 }
 
+/**
+ * Scan the docs/ directory and return prerender entries for all version root pages.
+ * This ensures adapter-static discovers and prerenders every version, not just the active one.
+ */
+function discoverVersionEntries(docsDir = path.join(process.cwd(), 'docs')) {
+  const entries = ['/']
+  try {
+    if (!fs.existsSync(docsDir)) return entries
+
+    const items = fs.readdirSync(docsDir, { withFileTypes: true })
+    for (const item of items) {
+      if (item.isDirectory() && /^v\d/.test(item.name)) {
+        entries.push(`/docs/${item.name}`)
+      }
+    }
+  } catch {
+    // Ignore errors — fall back to just '/'
+  }
+  return entries
+}
+
 /**
  * Create a full SvelteKit config with Specra defaults
  */
 export function specraConfig(options = {}) {
   const { vitePreprocess } = options.vitePreprocess || {}
+  const userPrerender = options.kit?.prerender || {}
 
   return {
     extensions: ['.svelte', '.md', '.svx', '.mdx'],
@@ -55,7 +79,14 @@ export function specraConfig(options = {}) {
       mdsvex(specraMdsvexConfig(options.mdsvex || {}))
     ],
     kit: {
-      ...(options.kit || {})
+      ...options.kit,
+      prerender: {
+        handleHttpError: 'warn',
+        handleMissingId: 'warn',
+        handleUnseenRoutes: 'warn',
+        entries: discoverVersionEntries(),
+        ...userPrerender,
+      }
     }
   }
 }

package/dist/components/docs/CategoryIndex.svelte

@@ -55,8 +55,12 @@
   const baseUrl = $derived(
     product && product !== '_default_'
       ? `/docs/${product}`
-      : (config.site?.baseUrl?.replace(/\/$/, '') || '')
+      : '/docs'
   );
+
+  // Note: We always use '/docs' as the base for non-product routes.
+  // Do NOT use config.site?.baseUrl here — that field (e.g. "/") refers to
+  // the site root, not the docs route prefix.
 </script>
 
 <div class="space-y-8">

package/dist/components/docs/MdxContent.svelte

@@ -26,7 +26,9 @@
     {#if Comp}
       {#if node.children && node.children.length > 0}
         <svelte:component this={Comp} {...node.props}>
-          <MdxContent nodes={node.children} {components} />
+          {#snippet children()}
+            <MdxContent nodes={node.children} {components} />
+          {/snippet}
         </svelte:component>
       {:else}
         <svelte:component this={Comp} {...node.props} />

package/dist/components/docs/SearchModal.svelte

@@ -28,7 +28,8 @@
   let inputEl = $state<HTMLInputElement | null>(null);
   let debounceTimer: ReturnType<typeof setTimeout> | null = null;
 
-  const baseUrl = $derived(config.site?.baseUrl || '/');
+  const siteBaseUrl = $derived(config.site?.baseUrl || '/');
+  const docsBaseUrl = '/docs';
 
   $effect(() => {
     if (isOpen && inputEl) {
@@ -75,7 +76,7 @@
     debounceTimer = setTimeout(async () => {
       try {
         const response = await fetch(
-          `${baseUrl.replace(/\/$/, '')}/api/search?q=${encodeURIComponent(value.trim())}`
+          `${siteBaseUrl.replace(/\/$/, '')}/api/search?q=${encodeURIComponent(value.trim())}`
         );
         if (response.ok) {
           const data = await response.json();
@@ -93,7 +94,7 @@
 
   function navigateToResult(result: SearchResult) {
     const version = result.version || config.site?.activeVersion || 'v1';
-    const url = `${baseUrl.replace(/\/$/, '')}/${version}/${result.slug}`;
+    const url = `${docsBaseUrl}/${version}/${result.slug}`;
     goto(url);
     onClose();
   }

package/dist/components/docs/SidebarMenuItems.svelte

@@ -57,7 +57,28 @@
       : `/docs/${version}`
   );
 
-  let collapsed: Record<string, boolean> = $state({});
+  const STORAGE_KEY = 'specra-sidebar-collapsed';
+
+  function loadCollapsedState(): Record<string, boolean> {
+    if (typeof window === 'undefined') return {};
+    try {
+      const stored = localStorage.getItem(STORAGE_KEY);
+      return stored ? JSON.parse(stored) : {};
+    } catch {
+      return {};
+    }
+  }
+
+  function saveCollapsedState(state: Record<string, boolean>) {
+    if (typeof window === 'undefined') return;
+    try {
+      localStorage.setItem(STORAGE_KEY, JSON.stringify(state));
+    } catch {
+      // localStorage unavailable
+    }
+  }
+
+  let collapsed: Record<string, boolean> = $state(loadCollapsedState());
   let pathname = $derived($page.url.pathname.replace(/\/$/, ''));
 
   // Filter docs by active tab group if tab groups are configured
@@ -180,6 +201,7 @@
 
   function toggleSection(section: string) {
     collapsed = { ...collapsed, [section]: !collapsed[section] };
+    saveCollapsedState(collapsed);
   }
 
   function isActiveInGroup(group: SidebarGroup): boolean {

package/dist/components/docs/api/ApiParams.svelte

@@ -13,62 +13,54 @@
   }
 
   let { title = 'Parameters', params }: Props = $props();
+
+  let filteredParams = $derived(
+    Array.isArray(params) ? params.filter(p => p && p.name) : []
+  );
 </script>
 
-{#if params && params.length > 0}
+{#if filteredParams.length > 0}
   <div class="mb-6">
     <h4 class="text-sm font-semibold text-foreground mb-3">{title}</h4>
-    <div class="overflow-x-auto">
-      <table class="w-full border-collapse">
+    <div class="specra-params-table">
+      <table>
         <thead>
-          <tr class="border-b border-border">
-            <th class="text-left py-2 px-3 text-xs font-semibold text-muted-foreground uppercase tracking-wider">
-              Property
-            </th>
-            <th class="text-left py-2 px-3 text-xs font-semibold text-muted-foreground uppercase tracking-wider">
-              Type
-            </th>
-            <th class="text-left py-2 px-3 text-xs font-semibold text-muted-foreground uppercase tracking-wider">
-              Required
-            </th>
-            <th class="text-left py-2 px-3 text-xs font-semibold text-muted-foreground uppercase tracking-wider">
-              Default
-            </th>
-            <th class="text-left py-2 px-3 text-xs font-semibold text-muted-foreground uppercase tracking-wider">
-              Description
-            </th>
+          <tr>
+            <th>Property</th>
+            <th>Type</th>
+            <th>Required</th>
+            <th>Default</th>
+            <th>Description</th>
           </tr>
         </thead>
         <tbody>
-          {#each params as param, index}
-            <tr
-              class={index !== params.length - 1 ? 'border-b border-border/50' : ''}
-            >
-              <td class="py-2.5 px-3">
-                <code class="text-sm font-mono text-foreground">{param.name}</code>
+          {#each filteredParams as param, index}
+            <tr>
+              <td>
+                <code>{param.name}</code>
               </td>
-              <td class="py-2.5 px-3">
-                <span class="text-sm text-muted-foreground font-mono">{param.type}</span>
+              <td>
+                <span class="font-mono">{param.type}</span>
               </td>
-              <td class="py-2.5 px-3">
+              <td>
                 {#if param.required}
-                  <span class="text-sm text-red-600 dark:text-red-400">Yes</span>
+                  <span class="text-red-600 dark:text-red-400">Yes</span>
                 {:else}
-                  <span class="text-sm text-muted-foreground">No</span>
+                  No
                 {/if}
               </td>
-              <td class="py-2.5 px-3">
+              <td>
                 {#if param.default}
-                  <code class="text-sm font-mono text-muted-foreground">{param.default}</code>
+                  <code>{param.default}</code>
                 {:else}
-                  <span class="text-sm text-muted-foreground">-</span>
+                  -
                 {/if}
               </td>
-              <td class="py-2.5 px-3">
+              <td>
                 {#if param.description}
-                  <span class="text-sm text-muted-foreground">{param.description}</span>
+                  {param.description}
                 {:else}
-                  <span class="text-sm text-muted-foreground">-</span>
+                  -
                 {/if}
               </td>
             </tr>
@@ -78,3 +70,69 @@
     </div>
   </div>
 {/if}
+
+<style>
+  .specra-params-table table {
+    border-collapse: separate;
+    border-spacing: 0;
+    border: 1px solid var(--border);
+    border-radius: 0.75rem;
+    overflow: hidden;
+    width: max-content;
+    max-width: 100%;
+    display: block;
+    overflow-x: auto;
+    -webkit-overflow-scrolling: touch;
+  }
+
+  .specra-params-table thead {
+    background: var(--muted);
+  }
+
+  .specra-params-table thead th {
+    border-bottom: 1px solid var(--border);
+    border-right: 1px solid var(--border);
+    padding: 0.625rem 1rem;
+    font-weight: 600;
+    font-size: 0.75rem;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    text-align: left;
+    color: var(--muted-foreground);
+    white-space: nowrap;
+  }
+
+  .specra-params-table thead th:last-child {
+    border-right: none;
+  }
+
+  .specra-params-table tbody td {
+    border-bottom: 1px solid var(--border);
+    border-right: 1px solid var(--border);
+    padding: 0.625rem 1rem;
+    font-size: 0.875rem;
+    color: var(--muted-foreground);
+  }
+
+  .specra-params-table tbody td:last-child {
+    border-right: none;
+  }
+
+  .specra-params-table tbody tr:last-child td {
+    border-bottom: none;
+  }
+
+  .specra-params-table tbody tr:hover {
+    background: var(--muted);
+  }
+
+  .specra-params-table code {
+    font-size: 0.8125rem;
+    font-family: var(--font-mono, ui-monospace, monospace);
+    color: var(--foreground);
+    background: var(--muted);
+    padding: 0.125rem 0.375rem;
+    border-radius: 0.25rem;
+    border: 1px solid var(--border);
+  }
+</style>

package/dist/components/ui/Button.svelte

@@ -36,23 +36,42 @@
 
 <script lang="ts">
   import { cn } from '../../utils.js';
-  import type { HTMLButtonAttributes } from 'svelte/elements';
+  import type { HTMLButtonAttributes, HTMLAnchorAttributes } from 'svelte/elements';
   import type { Snippet } from 'svelte';
 
-  interface Props extends HTMLButtonAttributes {
+  type ButtonProps = HTMLButtonAttributes & {
+    href?: never;
+  };
+
+  type AnchorProps = HTMLAnchorAttributes & {
+    href: string;
+  };
+
+  type Props = (ButtonProps | AnchorProps) & {
     variant?: ButtonVariants['variant'];
     size?: ButtonVariants['size'];
     class?: string;
     children?: Snippet;
-  }
+  };
 
-  let { variant = 'default', size = 'default', class: className, children, ...restProps }: Props = $props();
+  let { variant = 'default', size = 'default', class: className, children, href, ...restProps }: Props = $props();
 </script>
 
-<button
-  data-slot="button"
-  class={cn(buttonVariants({ variant, size, className }))}
-  {...restProps}
->
-  {@render children?.()}
-</button>
+{#if href}
+  <a
+    {href}
+    data-slot="button"
+    class={cn(buttonVariants({ variant, size, className }))}
+    {...restProps}
+  >
+    {@render children?.()}
+  </a>
+{:else}
+  <button
+    data-slot="button"
+    class={cn(buttonVariants({ variant, size, className }))}
+    {...restProps}
+  >
+    {@render children?.()}
+  </button>
+{/if}

package/dist/components/ui/Button.svelte.d.ts

@@ -4,14 +4,20 @@ export declare const buttonVariants: (props?: ({
     size?: "icon" | "default" | "sm" | "lg" | "icon-sm" | "icon-lg" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 export type ButtonVariants = VariantProps<typeof buttonVariants>;
-import type { HTMLButtonAttributes } from 'svelte/elements';
+import type { HTMLButtonAttributes, HTMLAnchorAttributes } from 'svelte/elements';
 import type { Snippet } from 'svelte';
-interface Props extends HTMLButtonAttributes {
+type ButtonProps = HTMLButtonAttributes & {
+    href?: never;
+};
+type AnchorProps = HTMLAnchorAttributes & {
+    href: string;
+};
+type Props = (ButtonProps | AnchorProps) & {
     variant?: ButtonVariants['variant'];
     size?: ButtonVariants['size'];
     class?: string;
     children?: Snippet;
-}
+};
 declare const Button: import("svelte").Component<Props, {}, "">;
 type Button = ReturnType<typeof Button>;
 export default Button;

package/dist/mdx.js

@@ -379,7 +379,14 @@ function parseJsxExpression(expr) {
             return JSON.parse(trimmed);
         }
         catch {
-            return trimmed;
+            // Convert JS object notation inside arrays to JSON
+            const jsonStr = trimmed.replace(/(\w+)\s*:/g, '"$1":').replace(/:\s*'([^']*)'/g, ': "$1"');
+            try {
+                return JSON.parse(jsonStr);
+            }
+            catch {
+                return trimmed;
+            }
         }
     }
     return trimmed;
@@ -449,6 +456,61 @@ function extractCodeBlockProps(node) {
     const filename = node.properties?.['data-filename'] || codeChild.properties?.['data-filename'];
     return { code, language, ...(filename ? { filename } : {}) };
 }
+/**
+ * Detect GitHub-style alert blockquotes: > [!WARNING] content
+ * Returns the alert type and remaining content children, or null if not an alert.
+ */
+const ALERT_TYPE_MAP = {
+    NOTE: 'note',
+    TIP: 'tip',
+    IMPORTANT: 'info',
+    WARNING: 'warning',
+    CAUTION: 'danger',
+    INFO: 'info',
+    SUCCESS: 'success',
+    ERROR: 'error',
+    DANGER: 'danger',
+};
+function extractBlockquoteAlert(node) {
+    if (node.type !== 'element' || node.tagName !== 'blockquote')
+        return null;
+    if (!node.children || node.children.length === 0)
+        return null;
+    // Find the first paragraph child
+    const firstP = node.children.find((c) => c.type === 'element' && c.tagName === 'p');
+    if (!firstP || !firstP.children || firstP.children.length === 0)
+        return null;
+    // Check first text node for [!TYPE] pattern
+    const firstText = firstP.children[0];
+    if (firstText.type !== 'text')
+        return null;
+    const match = firstText.value.match(/^\s*\[!(\w+)\]\s*\n?/);
+    if (!match)
+        return null;
+    const alertType = ALERT_TYPE_MAP[match[1].toUpperCase()];
+    if (!alertType)
+        return null;
+    // Build remaining content: modify the first paragraph to remove the alert marker
+    const remainingFirstPChildren = [...firstP.children];
+    const remainingText = firstText.value.slice(match[0].length);
+    if (remainingText.trim()) {
+        remainingFirstPChildren[0] = { ...firstText, value: remainingText };
+    }
+    else {
+        remainingFirstPChildren.shift();
+    }
+    const contentChildren = [];
+    if (remainingFirstPChildren.length > 0) {
+        contentChildren.push({ ...firstP, children: remainingFirstPChildren });
+    }
+    // Add any remaining blockquote children (paragraphs after the first)
+    for (const child of node.children) {
+        if (child !== firstP) {
+            contentChildren.push(child);
+        }
+    }
+    return { type: alertType, contentChildren };
+}
 /**
  * Recursively extract text content from a hast node.
  */
@@ -720,6 +782,20 @@ async function hastChildrenToMdxNodes(children) {
                 children: childNodes,
             });
         }
+        else if (extractBlockquoteAlert(child)) {
+            // GitHub-style alert blockquotes: > [!WARNING] content
+            flushHtmlBuffer();
+            const alert = extractBlockquoteAlert(child);
+            const contentNodes = alert.contentChildren.length > 0
+                ? await hastChildrenToMdxNodes(alert.contentChildren)
+                : [];
+            nodes.push({
+                type: 'component',
+                name: 'Callout',
+                props: { type: alert.type },
+                children: contentNodes,
+            });
+        }
         else {
             // Check if this regular element contains any component elements nested within
             if (hasNestedComponent(child)) {

package/dist/parsers/openapi-parser.js

@@ -116,8 +116,13 @@ export class OpenApiParser {
     parseParameters(parameters, spec) {
         const result = { path: [], query: [], header: [] };
         for (const param of parameters) {
+            if (!param)
+                continue;
             // Resolve $ref if present
             const resolved = param.$ref ? this.resolveRef(param.$ref, spec) : param;
+            // Skip params that failed to resolve or have no name
+            if (!resolved || !resolved.name || !resolved.in)
+                continue;
             const apiParam = {
                 name: resolved.name,
                 type: resolved.schema?.type || resolved.type || "string",
@@ -202,7 +207,7 @@ export class OpenApiParser {
         for (const segment of path) {
             current = current[segment];
             if (!current)
-                return {};
+                return null;
         }
         return current;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specra",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "description": "A modern documentation library for SvelteKit with built-in versioning, API reference generation, full-text search, and MDX support",
   "svelte": "./dist/index.js",
   "types": "./dist/index.d.ts",