specra 0.2.6 → 0.2.8

package/dist/components/docs/ProductSwitcher.svelte.d.ts

@@ -0,0 +1,28 @@
+/** Flat shape (from page components) */
+interface ProductItemFlat {
+    slug: string;
+    label: string;
+    icon?: string;
+    badge?: string;
+    activeVersion?: string;
+    isDefault: boolean;
+}
+/** Nested shape (from SDK getProducts()) */
+interface ProductItemNested {
+    slug: string;
+    config: {
+        label: string;
+        icon?: string;
+        badge?: string;
+        activeVersion?: string;
+    };
+    isDefault: boolean;
+}
+type ProductInput = ProductItemFlat | ProductItemNested;
+interface Props {
+    products: ProductInput[];
+    currentProduct?: string;
+}
+declare const ProductSwitcher: import("svelte").Component<Props, {}, "">;
+type ProductSwitcher = ReturnType<typeof ProductSwitcher>;
+export default ProductSwitcher;

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/Sidebar.svelte

@@ -26,12 +26,13 @@
   interface Props {
     docs: DocItem[];
     version: string;
+    product?: string;
     onLinkClick?: () => void;
     config: SpecraConfig;
     activeTabGroup?: string;
   }
 
-  let { docs, version, onLinkClick, config, activeTabGroup }: Props = $props();
+  let { docs = [], version, product, onLinkClick, config, activeTabGroup }: Props = $props();
 
   let isFlush = $derived(config.navigation?.sidebarStyle === 'flush');
   let containerClass = $derived(
@@ -53,6 +54,7 @@
       <SidebarMenuItems
         {docs}
         {version}
+        {product}
         {onLinkClick}
         {config}
         {activeTabGroup}

package/dist/components/docs/Sidebar.svelte.d.ts

@@ -22,6 +22,7 @@ interface DocItem {
 interface Props {
     docs: DocItem[];
     version: string;
+    product?: string;
     onLinkClick?: () => void;
     config: SpecraConfig;
     activeTabGroup?: string;

package/dist/components/docs/SidebarMenuItems.svelte

@@ -42,14 +42,43 @@
   interface Props {
     docs: DocItem[];
     version: string;
+    product?: string;
     onLinkClick?: () => void;
     config: SpecraConfig;
     activeTabGroup?: string;
   }
 
-  let { docs, version, onLinkClick, config, activeTabGroup }: Props = $props();
+  let { docs = [], version, product, onLinkClick, config, activeTabGroup }: Props = $props();
 
-  let collapsed: Record<string, boolean> = $state({});
+  /** URL prefix: /docs/{product}/{version} for named products, /docs/{version} for default */
+  let docsBase = $derived(
+    product && product !== '_default_'
+      ? `/docs/${product}/${version}`
+      : `/docs/${version}`
+  );
+
+  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
@@ -172,18 +201,19 @@
 
   function toggleSection(section: string) {
     collapsed = { ...collapsed, [section]: !collapsed[section] };
+    saveCollapsedState(collapsed);
   }
 
   function isActiveInGroup(group: SidebarGroup): boolean {
     const hasActiveItem = group.items.some(
-      (doc) => pathname === `/docs/${version}/${doc.slug}`
+      (doc) => pathname === `${docsBase}/${doc.slug}`
     );
     if (hasActiveItem) return true;
     return Object.values(group.children).some((child) => isActiveInGroup(child));
   }
 
   function getGroupHref(group: SidebarGroup): string {
-    let groupHref = `/docs/${version}/${group.path}`;
+    let groupHref = `${docsBase}/${group.path}`;
 
     if (config.features?.i18n) {
       const i18n = config.features.i18n;
@@ -192,7 +222,7 @@
       const potentialLocale = pathParts[3];
 
       if (potentialLocale && locales.includes(potentialLocale)) {
-        groupHref = `/docs/${version}/${potentialLocale}/${group.path}`;
+        groupHref = `${docsBase}/${potentialLocale}/${group.path}`;
       }
     }
 
@@ -201,7 +231,7 @@
 
   function isGroupCollapsed(groupKey: string, group: SidebarGroup): boolean {
     const hasActive = isActiveInGroup(group);
-    const isGroupActive = pathname === `/docs/${version}/${group.path}`;
+    const isGroupActive = pathname === `${docsBase}/${group.path}`;
     if (hasActive || isGroupActive) return false;
     return collapsed[groupKey] ?? group.defaultCollapsed;
   }
@@ -240,7 +270,7 @@
   {@const hasChildren = sortedChildren.length > 0}
   {@const hasItems = sortedItems.length > 0}
   {@const hasContent = hasChildren || hasItems}
-  {@const isGroupActive = pathname === `/docs/${version}/${group.path}`}
+  {@const isGroupActive = pathname === `${docsBase}/${group.path}`}
   {@const isCollapsed = isGroupCollapsed(groupKey, group)}
   {@const marginLeft = depth > 0 ? 'ml-4' : ''}
   {@const groupHref = getGroupHref(group)}
@@ -289,7 +319,7 @@
           {#if item.type === 'group'}
             {@render renderGroup(`${groupKey}/${item.key}`, item.group, depth + 1)}
           {:else}
-            {@const href = `/docs/${version}/${item.doc.slug}`}
+            {@const href = `${docsBase}/${item.doc.slug}`}
             {@const isActive = pathname === href}
             <a
               {href}
@@ -316,7 +346,7 @@
 <nav class="space-y-1">
   {#if sortedStandalone.length > 0}
     {#each sortedStandalone as doc (doc.slug)}
-      {@const href = `/docs/${version}/${doc.slug}`}
+      {@const href = `${docsBase}/${doc.slug}`}
       {@const isActive = pathname === href}
       <a
         {href}

package/dist/components/docs/SidebarMenuItems.svelte.d.ts

@@ -24,6 +24,7 @@ interface DocItem {
 interface Props {
     docs: DocItem[];
     version: string;
+    product?: string;
     onLinkClick?: () => void;
     config: SpecraConfig;
     activeTabGroup?: string;

package/dist/components/docs/TabGroups.svelte

@@ -24,10 +24,17 @@
     mobileOnly?: boolean;
     docs?: DocItem[];
     version?: string;
+    product?: string;
     flush?: boolean;
   }
 
-  let { tabGroups, activeTabId, onTabChange, mobileOnly = false, docs, version, flush = false }: Props = $props();
+  let { tabGroups, activeTabId, onTabChange, mobileOnly = false, docs, version, product, flush = false }: Props = $props();
+
+  let docsBase = $derived(
+    product && product !== '_default_' && version
+      ? `/docs/${product}/${version}`
+      : version ? `/docs/${version}` : '/docs'
+  );
 
   let dropdownOpen = $state(false);
 
@@ -58,7 +65,7 @@
       });
 
       if (firstDocInTab) {
-        goto(`/docs/${version}/${firstDocInTab.slug}`);
+        goto(`${docsBase}/${firstDocInTab.slug}`);
       }
     }
   }

package/dist/components/docs/TabGroups.svelte.d.ts

@@ -18,6 +18,7 @@ interface Props {
     mobileOnly?: boolean;
     docs?: DocItem[];
     version?: string;
+    product?: string;
     flush?: boolean;
 }
 declare const TabGroups: import("svelte").Component<Props, {}, "">;

package/dist/components/docs/VersionSwitcher.svelte

@@ -27,7 +27,7 @@
     if (versionsMeta && versionsMeta.length > 0) {
       return versionsMeta.filter(v => !v.hidden);
     }
-    return versions.map(id => ({ id, label: id }));
+    return (versions ?? []).map(id => ({ id, label: id }));
   });
 
   // Get current version display label

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/docs/index.d.ts

@@ -51,6 +51,7 @@ export { default as TimelineItem } from './TimelineItem.svelte';
 export { default as Tabs } from './Tabs.svelte';
 export { default as ThemeToggle } from './ThemeToggle.svelte';
 export { default as Tooltip } from './Tooltip.svelte';
+export { default as ProductSwitcher } from './ProductSwitcher.svelte';
 export { default as VersionBanner } from './VersionBanner.svelte';
 export { default as VersionSwitcher } from './VersionSwitcher.svelte';
 export { default as Video } from './Video.svelte';

package/dist/components/docs/index.js

@@ -52,6 +52,7 @@ export { default as TimelineItem } from './TimelineItem.svelte';
 export { default as Tabs } from './Tabs.svelte';
 export { default as ThemeToggle } from './ThemeToggle.svelte';
 export { default as Tooltip } from './Tooltip.svelte';
+export { default as ProductSwitcher } from './ProductSwitcher.svelte';
 export { default as VersionBanner } from './VersionBanner.svelte';
 export { default as VersionSwitcher } from './VersionSwitcher.svelte';
 export { default as Video } from './Video.svelte';

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

@@ -1,17 +1,23 @@
 import { type VariantProps } from 'class-variance-authority';
 export declare const buttonVariants: (props?: ({
     variant?: "link" | "default" | "destructive" | "outline" | "secondary" | "ghost" | null | undefined;
-    size?: "default" | "icon" | "sm" | "lg" | "icon-sm" | "icon-lg" | null | undefined;
+    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/config.d.ts

@@ -4,5 +4,5 @@
  * The actual config loading happens on the server and is passed as props
  */
 export { defaultConfig } from "./config.types";
-export type { SpecraConfig, VersionConfig, BannerConfig } from "./config.types";
+export type { SpecraConfig, VersionConfig, BannerConfig, ProductConfig, Product, DefaultProductConfig } from "./config.types";
 export { getConfig, getConfigValue, loadConfig, processContentWithEnv, replaceEnvVariables, validateConfig, reloadConfig, } from "./config.server";

package/dist/config.schema.json

@@ -74,6 +74,24 @@
         "hideLogo": {
           "type": "boolean",
           "description": "Whether to hide the site logo in the header"
+        },
+        "defaultProduct": {
+          "type": "object",
+          "description": "Configuration for the default product in multi-product mode. Falls back to site title and activeVersion if not set.",
+          "properties": {
+            "label": {
+              "type": "string",
+              "description": "Display name for the default product in the switcher"
+            },
+            "icon": {
+              "type": "string",
+              "description": "Icon for the default product (lucide icon name)"
+            },
+            "activeVersion": {
+              "type": "string",
+              "description": "Override active version for the default product"
+            }
+          }
         }
       }
     },

package/dist/config.server.d.ts

@@ -1,4 +1,4 @@
-import type { SpecraConfig, VersionConfig } from "./config.types";
+import type { SpecraConfig, VersionConfig, ProductConfig, Product } from "./config.types";
 /**
  * Load and parse the Specra configuration file
  * Falls back to default configuration if file doesn't exist or is invalid
@@ -41,13 +41,13 @@ export declare function getConfig(): SpecraConfig;
  * Reload the configuration (useful for development) (SERVER ONLY)
  */
 export declare function reloadConfig(userConfig: Partial<SpecraConfig>): SpecraConfig;
-export declare function loadVersionConfig(version: string): VersionConfig | null;
+export declare function loadVersionConfig(version: string, product?: string): VersionConfig | null;
 /**
- * Get the effective config for a specific version.
- * Merges global config with per-version overrides from _version_.json.
- * If no _version_.json exists, returns the global config unchanged.
+ * Get the effective config for a specific version and optional product.
+ * Merges in priority order: global ← product ← version.
+ * If no overrides exist, returns the global config unchanged.
  */
-export declare function getEffectiveConfig(version: string): SpecraConfig;
+export declare function getEffectiveConfig(version: string, product?: string): SpecraConfig;
 /**
  * Version metadata for display in the version switcher.
  */
@@ -67,7 +67,35 @@ export interface VersionMeta {
  * Get metadata for all versions, enriched with _version_.json data.
  * Hidden versions are included but marked — the UI decides whether to show them.
  */
-export declare function getVersionsMeta(versions: string[]): VersionMeta[];
+export declare function getVersionsMeta(versions: string[], product?: string): VersionMeta[];
+/**
+ * Load and parse a _product_.json file for a given product slug.
+ * Returns null if the file doesn't exist or is invalid.
+ */
+export declare function loadProductConfig(product: string): ProductConfig | null;
+/**
+ * Scan docs/ top-level directories for _product_.json files.
+ * Returns the full list of products including the default product.
+ *
+ * Detection logic:
+ * 1. Single readdir + stat calls — no recursive walks
+ * 2. If no _product_.json found → single-product mode (returns empty array)
+ * 3. If any found → multi-product mode; bare version folders become the default product
+ * 4. Product slugs that match version patterns (e.g., v1.0.0) are rejected with a clear error
+ */
+export declare function scanProducts(): Product[];
+/**
+ * Get all products (cached). Returns empty array in single-product mode.
+ */
+export declare function getProducts(): Product[];
+/**
+ * Check if the site is in multi-product mode.
+ */
+export declare function isMultiProductMode(): boolean;
+/**
+ * Clear product-related caches. Called by file watchers when _product_.json changes.
+ */
+export declare function clearProductCaches(): void;
 /**
  * Export the loaded config as default (SERVER ONLY)
  */