specra 0.2.8 → 0.2.10

package/config/category.schema.json

@@ -0,0 +1,52 @@
+{
+  "$ref": "#/definitions/CategoryConfig",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "definitions": {
+    "CategoryConfig": {
+      "additionalProperties": false,
+      "properties": {
+        "collapsed": {
+          "type": "boolean"
+        },
+        "collapsible": {
+          "type": "boolean"
+        },
+        "icon": {
+          "type": "string"
+        },
+        "label": {
+          "type": "string"
+        },
+        "link": {
+          "additionalProperties": false,
+          "properties": {
+            "slug": {
+              "type": "string"
+            },
+            "type": {
+              "enum": [
+                "generated-index",
+                "doc"
+              ],
+              "type": "string"
+            }
+          },
+          "required": [
+            "type"
+          ],
+          "type": "object"
+        },
+        "position": {
+          "type": "number"
+        },
+        "sidebar_position": {
+          "type": "number"
+        },
+        "tab_group": {
+          "type": "string"
+        }
+      },
+      "type": "object"
+    }
+  }
+}

package/config/product.schema.json

@@ -0,0 +1,70 @@
+{
+  "$ref": "#/definitions/ProductConfig",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "definitions": {
+    "ProductConfig": {
+      "additionalProperties": false,
+      "description": "Per-product configuration loaded from docs/{product}/_product_.json Products sit above versions in the config hierarchy.",
+      "properties": {
+        "activeVersion": {
+          "description": "Default version for this product (overrides global site.activeVersion)",
+          "type": "string"
+        },
+        "badge": {
+          "description": "Badge text shown next to the product (e.g., \"New\", \"Beta\")",
+          "type": "string"
+        },
+        "description": {
+          "description": "Short description of the product",
+          "type": "string"
+        },
+        "icon": {
+          "description": "Icon identifier for the product dropdown (lucide icon name)",
+          "type": "string"
+        },
+        "label": {
+          "description": "Display name in the product switcher",
+          "type": "string"
+        },
+        "position": {
+          "description": "Order in the product dropdown (lower = first)",
+          "type": "number"
+        },
+        "tabGroups": {
+          "description": "Product-level tab group overrides",
+          "items": {
+            "$ref": "#/definitions/TabGroup"
+          },
+          "type": "array"
+        }
+      },
+      "required": [
+        "label"
+      ],
+      "type": "object"
+    },
+    "TabGroup": {
+      "additionalProperties": false,
+      "description": "Tab group for organizing documentation",
+      "properties": {
+        "icon": {
+          "description": "Optional icon name (lucide-react icon)",
+          "type": "string"
+        },
+        "id": {
+          "description": "Unique identifier for the tab group",
+          "type": "string"
+        },
+        "label": {
+          "description": "Display label for the tab",
+          "type": "string"
+        }
+      },
+      "required": [
+        "id",
+        "label"
+      ],
+      "type": "object"
+    }
+  }
+}

package/config/version.schema.json

@@ -0,0 +1,83 @@
+{
+  "$ref": "#/definitions/VersionConfig",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "definitions": {
+    "BannerConfig": {
+      "additionalProperties": false,
+      "description": "Banner configuration for version-level or site-level banners.   Site-wide banner configuration",
+      "properties": {
+        "text": {
+          "description": "Banner message text. Supports markdown links like [text](/url).",
+          "type": "string"
+        },
+        "type": {
+          "description": "Banner style: info, warning, error, success   Banner type",
+          "enum": [
+            "info",
+            "warning",
+            "error",
+            "success"
+          ],
+          "type": "string"
+        }
+      },
+      "required": [
+        "text"
+      ],
+      "type": "object"
+    },
+    "TabGroup": {
+      "additionalProperties": false,
+      "description": "Tab group for organizing documentation",
+      "properties": {
+        "icon": {
+          "description": "Optional icon name (lucide-react icon)",
+          "type": "string"
+        },
+        "id": {
+          "description": "Unique identifier for the tab group",
+          "type": "string"
+        },
+        "label": {
+          "description": "Display label for the tab",
+          "type": "string"
+        }
+      },
+      "required": [
+        "id",
+        "label"
+      ],
+      "type": "object"
+    },
+    "VersionConfig": {
+      "additionalProperties": false,
+      "description": "Per-version configuration that can override global config settings. Loaded from docs/{version}/_version_.json",
+      "properties": {
+        "badge": {
+          "description": "Short badge text shown next to the version (e.g., \"Beta\", \"LTS\", \"Deprecated\").",
+          "type": "string"
+        },
+        "banner": {
+          "$ref": "#/definitions/BannerConfig",
+          "description": "Banner shown at the top of every page in this version. Overrides global banner."
+        },
+        "hidden": {
+          "description": "Hide this version from the version switcher. Useful for unreleased versions.",
+          "type": "boolean"
+        },
+        "label": {
+          "description": "Display label for this version (e.g., \"v1.0 (Stable)\"). Defaults to directory name.",
+          "type": "string"
+        },
+        "tabGroups": {
+          "description": "Override tab groups for this version. Empty array = no tabs.",
+          "items": {
+            "$ref": "#/definitions/TabGroup"
+          },
+          "type": "array"
+        }
+      },
+      "type": "object"
+    }
+  }
+}

package/dist/category.js

@@ -1,7 +1,7 @@
 // Note: This file uses server-only APIs (fs, path) and should only be imported in Server Components
 import fs from "fs";
 import path from "path";
-const DOCS_DIR = path.join(process.cwd(), "docs");
+const DOCS_DIR = typeof process !== 'undefined' ? path.join(process.cwd(), "docs") : "docs";
 /**
  * Read category.json from a folder
  */

package/dist/components/docs/CategoryIndex.svelte

@@ -42,8 +42,8 @@
         // Match direct children of this category path
         if (!docPath.startsWith(categoryPath + '/')) return false;
         const remaining = docPath.slice(categoryPath.length + 1);
-        // Only direct children (no further slashes, or is an index)
-        return !remaining.includes('/') && remaining !== 'index';
+        // Only direct children (no further slashes)
+        return !remaining.includes('/');
       })
       .sort((a, b) => {
         const posA = a.meta?.sidebar_position ?? 999;

package/dist/components/docs/MdxContent.svelte

@@ -1,14 +1,7 @@
 <script lang="ts">
   import MdxContent from './MdxContent.svelte';
   import type { Component } from 'svelte';
-
-  interface MdxNode {
-    type: 'html' | 'component';
-    content?: string;
-    name?: string;
-    props?: Record<string, any>;
-    children?: MdxNode[];
-  }
+  import type { MdxNode } from '../../mdx.js';
 
   interface Props {
     nodes: MdxNode[];

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

@@ -0,0 +1,10 @@
+import MdxContent from './MdxContent.svelte';
+import type { Component } from 'svelte';
+import type { MdxNode } from '../../mdx.js';
+interface Props {
+    nodes: MdxNode[];
+    components: Record<string, Component>;
+}
+declare const MdxContent: Component<Props, {}, "">;
+type MdxContent = ReturnType<typeof MdxContent>;
+export default MdxContent;

package/dist/components/docs/NotFoundContent.svelte

@@ -3,11 +3,19 @@
 
   interface Props {
     version?: string;
+    product?: string;
   }
 
-  let { version = '' }: Props = $props();
+  let { version = '', product = '' }: Props = $props();
 
-  const homeLink = $derived(version ? `/${version}` : '/');
+  /** URL prefix: /docs/{product}/{version} for named products, /docs/{version} for default */
+  const homeLink = $derived(
+    product && product !== '_default_' && version
+      ? `/docs/${product}/${version}`
+      : version
+        ? `/docs/${version}`
+        : '/'
+  );
 </script>
 
 <div class="flex flex-col items-center justify-center min-h-[60vh] text-center px-4">

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

@@ -1,5 +1,6 @@
 interface Props {
     version?: string;
+    product?: string;
 }
 declare const NotFoundContent: import("svelte").Component<Props, {}, "">;
 type NotFoundContent = ReturnType<typeof NotFoundContent>;

package/dist/components/docs/SidebarMenuItems.svelte

@@ -134,9 +134,8 @@
         if (isIndexFile) {
           rootGroups[groupName].position = doc.sidebar_position ?? 999;
           rootGroups[groupName].icon = doc.categoryIcon;
-        } else {
-          rootGroups[groupName].items.push(doc);
         }
+        rootGroups[groupName].items.push(doc);
         return;
       }
 
@@ -179,17 +178,14 @@
               if (doc.categoryIcon) {
                 currentLevel[folder].icon = doc.categoryIcon;
               }
-            } else {
-              currentLevel[folder].items.push(doc);
             }
+            currentLevel[folder].items.push(doc);
           }
 
           currentLevel = currentLevel[folder].children;
         }
       } else {
-        if (!isIndexFile) {
-          standalone.push(doc);
-        }
+        standalone.push(doc);
       }
     });
 

package/dist/config.server.js

@@ -150,7 +150,7 @@ export function reloadConfig(userConfig) {
  * Returns null if the file doesn't exist or is invalid.
  */
 const versionConfigCache = new Map();
-const VCFG_TTL = process.env.NODE_ENV === 'development' ? 5000 : 60000;
+const VCFG_TTL = (typeof process !== 'undefined' && process.env?.NODE_ENV === 'development') ? 5000 : 60000;
 export function loadVersionConfig(version, product) {
     const cacheKey = product && product !== "_default_" ? `${product}:${version}` : version;
     const cached = versionConfigCache.get(cacheKey);
@@ -240,7 +240,7 @@ const productsCache = {
     data: null,
     timestamp: 0,
 };
-const PCFG_TTL = process.env.NODE_ENV === 'development' ? 5000 : 60000;
+const PCFG_TTL = (typeof process !== 'undefined' && process.env?.NODE_ENV === 'development') ? 5000 : 60000;
 /** Cache for individual product configs */
 const productConfigCache = new Map();
 /**

package/dist/dev-utils.js

@@ -2,7 +2,7 @@
  * Development utilities for debugging and performance monitoring
  * Only active in development mode
  */
-const isDevelopment = process.env.NODE_ENV === 'development';
+const isDevelopment = typeof process !== 'undefined' && process.env?.NODE_ENV === 'development';
 /**
  * Performance timer for measuring operation duration
  */

package/dist/mdx-cache.js

@@ -10,7 +10,7 @@ import { clearProductCaches } from './config.server';
 import { watch } from 'fs';
 import { join } from 'path';
 import { PerfTimer, logCacheOperation } from './dev-utils';
-const isDevelopment = process.env.NODE_ENV === 'development';
+const isDevelopment = typeof process !== 'undefined' && process.env?.NODE_ENV === 'development';
 // Cache stores
 const versionsCache = {
     data: null,

package/dist/mdx-components.d.ts

@@ -0,0 +1,22 @@
+/**
+ * MDX/mdsvex component map for Specra documentation.
+ *
+ * In mdsvex, custom components are imported directly in .svx files.
+ * This file exports the component map for programmatic use.
+ *
+ * Usage in .svx files:
+ * ```svelte
+ * <script>
+ *   import { Callout, CodeBlock, Tabs, Tab } from 'specra/components'
+ * </script>
+ *
+ * <Callout type="info">This is a callout</Callout>
+ * ```
+ */
+import type { Component } from 'svelte';
+import { Callout, Accordion, AccordionItem, Tabs, Tab, Image, Video, Card, CardGrid, ImageCard, ImageCardGrid, Steps, Step, Icon, Mermaid, Math, Columns, Column, DocBadge, Tooltip, Frame, CodeBlock, Timeline, TimelineItem, ApiEndpoint, ApiParams, ApiResponse, ApiPlayground, ApiReference } from './components/docs';
+export { Callout, Accordion, AccordionItem, Tabs, Tab, Image, Video, Card, CardGrid, ImageCard, ImageCardGrid, Steps, Step, Icon, Mermaid, Math, Columns, Column, DocBadge, Tooltip, Frame, CodeBlock, Timeline, TimelineItem, ApiEndpoint, ApiParams, ApiResponse, ApiPlayground, ApiReference, };
+/**
+ * Component map for passing to layout components that render MDX content.
+ */
+export declare const mdxComponents: Record<string, Component>;

package/dist/mdx.js

@@ -15,7 +15,7 @@ import { getAllCategoryConfigs } from "./category";
 import { sortSidebarItems, sortSidebarGroups, buildSidebarStructure } from "./sidebar-utils";
 import { sanitizePath, validatePathWithinDirectory, validateMDXSecurity } from "./mdx-security";
 import { getConfig } from "./config";
-const DOCS_DIR = path.join(process.cwd(), "docs");
+const DOCS_DIR = typeof process !== 'undefined' ? path.join(process.cwd(), "docs") : "docs";
 /**
  * Resolve the docs directory for a given version and optional product.
  * - Default product or omitted: docs/{version}/

package/dist/sidebar-utils.js

@@ -79,13 +79,10 @@ export function buildSidebarStructure(docs) {
                 };
             }
             if (isIndexFile) {
-                // Use categoryPosition if available (from _category_.json), otherwise sidebar_position from frontmatter
                 rootGroups[groupName].position = doc.categoryPosition ?? doc.meta.sidebar_position ?? 999;
                 rootGroups[groupName].icon = doc.categoryIcon;
             }
-            else {
-                rootGroups[groupName].items.push(doc);
-            }
+            rootGroups[groupName].items.push(doc);
             return;
         }
         if (pathParts.length > 1) {
@@ -127,17 +124,13 @@ export function buildSidebarStructure(docs) {
                             currentLevel[folder].defaultCollapsed = doc.categoryCollapsed;
                         }
                     }
-                    else {
-                        currentLevel[folder].items.push(doc);
-                    }
+                    currentLevel[folder].items.push(doc);
                 }
                 currentLevel = currentLevel[folder].children;
             }
         }
         else {
-            if (!isIndexFile) {
-                standalone.push(doc);
-            }
+            standalone.push(doc);
         }
     });
     return { rootGroups, standalone };

package/dist/styles/globals.css

@@ -159,28 +159,39 @@
     text-decoration: none;
   }
 
-  /* Link styling - primary color, no underline until hover */
+  /* Prose text links - underlined for readability */
   main .prose a {
     color: var(--color-primary);
-    text-decoration: none;
-    transition: color 0.2s ease, text-decoration 0.2s ease;
+    text-decoration: underline;
+    text-underline-offset: 3px;
+    text-decoration-thickness: 1px;
+    text-decoration-color: color-mix(in srgb, var(--color-primary) 40%, transparent);
+    transition: text-decoration-color 0.2s ease;
   }
 
   main .prose a:hover {
-    text-decoration: none !important;
-    color: var(--color-primary);
+    text-decoration-color: var(--color-primary);
   }
 
-  /* Prose links in documentation */
   .prose a {
     color: var(--color-primary);
-    text-decoration: none !important;
+    text-decoration: underline;
+    text-underline-offset: 3px;
+    text-decoration-thickness: 1px;
+    text-decoration-color: color-mix(in srgb, var(--color-primary) 40%, transparent);
     font-weight: 500;
   }
 
   .prose a:hover {
+    text-decoration-color: var(--color-primary);
+  }
+
+  /* Navigation/UI links inside prose - no underline */
+  .prose .not-prose a,
+  .prose nav a,
+  .prose [data-doc-nav] a,
+  .prose .doc-navigation a {
     text-decoration: none !important;
-    color: var(--color-primary);
   }
 
   /* Sidebar links - no underline on hover */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specra",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "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",
@@ -34,7 +34,10 @@
     },
     "./styles": "./dist/styles/globals.css",
     "./styles.css": "./dist/styles/globals.css",
-    "./config.schema.json": "./config/specra.config.schema.json"
+    "./config.schema.json": "./config/specra.config.schema.json",
+    "./version.schema.json": "./config/version.schema.json",
+    "./product.schema.json": "./config/product.schema.json",
+    "./category.schema.json": "./config/category.schema.json"
   },
   "files": [
     "dist",
@@ -45,7 +48,7 @@
     "dev": "svelte-package --watch",
     "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
     "typecheck": "svelte-check --tsconfig ./tsconfig.json",
-    "generate:schema": "ts-json-schema-generator --path src/lib/config.types.ts --type SpecraConfig --out config/specra.config.schema.json"
+    "generate:schema": "ts-json-schema-generator --path src/lib/config.types.ts --type SpecraConfig --out config/specra.config.schema.json && ts-json-schema-generator --path src/lib/config.types.ts --type VersionConfig --out config/version.schema.json && ts-json-schema-generator --path src/lib/config.types.ts --type ProductConfig --out config/product.schema.json && ts-json-schema-generator --path src/lib/category.ts --type CategoryConfig --out config/category.schema.json"
   },
   "keywords": [
     "documentation",