specra 0.1.13 → 0.2.0

package/dist/components/docs/SearchHighlight.svelte

@@ -0,0 +1,116 @@
+<script lang="ts">
+  import { page } from '$app/stores';
+  import { browser } from '$app/environment';
+
+  const searchQuery = $derived($page.url.searchParams.get('q') || $page.url.searchParams.get('query') || '');
+
+  $effect(() => {
+    if (!browser || !searchQuery) return;
+
+    // Wait for content to render
+    const timer = setTimeout(() => {
+      highlightSearchTerms(searchQuery);
+    }, 100);
+
+    return () => {
+      clearTimeout(timer);
+      removeHighlights();
+    };
+  });
+
+  function highlightSearchTerms(query: string) {
+    if (!query.trim()) return;
+
+    // Remove any existing highlights first
+    removeHighlights();
+
+    const contentEl = document.querySelector('[data-doc-content]') || document.querySelector('.prose') || document.querySelector('main');
+    if (!contentEl) return;
+
+    const walker = document.createTreeWalker(contentEl, NodeFilter.SHOW_TEXT, {
+      acceptNode(node) {
+        // Skip script, style, and already-highlighted nodes
+        const parent = node.parentElement;
+        if (!parent) return NodeFilter.FILTER_REJECT;
+        const tagName = parent.tagName.toLowerCase();
+        if (tagName === 'script' || tagName === 'style' || tagName === 'code' || tagName === 'pre') {
+          return NodeFilter.FILTER_REJECT;
+        }
+        if (parent.classList.contains('search-highlight')) {
+          return NodeFilter.FILTER_REJECT;
+        }
+        return NodeFilter.FILTER_ACCEPT;
+      }
+    });
+
+    const textNodes: Text[] = [];
+    let currentNode: Node | null;
+    while ((currentNode = walker.nextNode())) {
+      textNodes.push(currentNode as Text);
+    }
+
+    const escaped = query.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const regex = new RegExp(`(${escaped})`, 'gi');
+
+    let firstHighlight: HTMLElement | null = null;
+
+    for (const textNode of textNodes) {
+      const text = textNode.textContent || '';
+      if (!regex.test(text)) continue;
+
+      // Reset regex lastIndex
+      regex.lastIndex = 0;
+
+      const fragment = document.createDocumentFragment();
+      let lastIndex = 0;
+      let match: RegExpExecArray | null;
+
+      while ((match = regex.exec(text)) !== null) {
+        // Add text before match
+        if (match.index > lastIndex) {
+          fragment.appendChild(document.createTextNode(text.slice(lastIndex, match.index)));
+        }
+
+        // Add highlighted match
+        const mark = document.createElement('mark');
+        mark.className = 'search-highlight bg-primary/20 text-primary rounded-sm px-0.5';
+        mark.textContent = match[1];
+        fragment.appendChild(mark);
+
+        if (!firstHighlight) {
+          firstHighlight = mark;
+        }
+
+        lastIndex = match.index + match[0].length;
+      }
+
+      // Add remaining text
+      if (lastIndex < text.length) {
+        fragment.appendChild(document.createTextNode(text.slice(lastIndex)));
+      }
+
+      textNode.parentNode?.replaceChild(fragment, textNode);
+    }
+
+    // Scroll to first highlight
+    if (firstHighlight) {
+      setTimeout(() => {
+        firstHighlight?.scrollIntoView({ behavior: 'smooth', block: 'center' });
+      }, 200);
+    }
+  }
+
+  function removeHighlights() {
+    if (!browser) return;
+    const highlights = document.querySelectorAll('.search-highlight');
+    highlights.forEach((mark) => {
+      const parent = mark.parentNode;
+      if (parent) {
+        parent.replaceChild(document.createTextNode(mark.textContent || ''), mark);
+        parent.normalize();
+      }
+    });
+  }
+</script>
+
+<!-- SearchHighlight is a side-effect only component, no visible output -->

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

@@ -0,0 +1,3 @@
+declare const SearchHighlight: import("svelte").Component<Record<string, never>, {}, "">;
+type SearchHighlight = ReturnType<typeof SearchHighlight>;
+export default SearchHighlight;

package/dist/components/docs/SearchModal.svelte

@@ -0,0 +1,239 @@
+<script lang="ts">
+  import { Search, X, FileText, Hash, ArrowUp, ArrowDown, CornerDownLeft, Loader2 } from 'lucide-svelte';
+  import { goto } from '$app/navigation';
+  import { browser } from '$app/environment';
+  import type { SpecraConfig } from '../../config.types.js';
+
+  interface SearchResult {
+    slug: string;
+    title: string;
+    description?: string;
+    excerpt?: string;
+    version?: string;
+    headings?: Array<{ id: string; title: string }>;
+  }
+
+  interface Props {
+    isOpen: boolean;
+    onClose: () => void;
+    config: SpecraConfig;
+  }
+
+  let { isOpen, onClose, config }: Props = $props();
+
+  let query = $state('');
+  let results = $state<SearchResult[]>([]);
+  let isLoading = $state(false);
+  let selectedIndex = $state(0);
+  let inputEl = $state<HTMLInputElement | null>(null);
+  let debounceTimer: ReturnType<typeof setTimeout> | null = null;
+
+  const baseUrl = $derived(config.site?.baseUrl || '/');
+
+  $effect(() => {
+    if (isOpen && inputEl) {
+      // Focus input when modal opens
+      setTimeout(() => inputEl?.focus(), 50);
+    }
+    if (!isOpen) {
+      query = '';
+      results = [];
+      selectedIndex = 0;
+      isLoading = false;
+    }
+  });
+
+  $effect(() => {
+    if (!browser) return;
+
+    function handleKeydown(e: KeyboardEvent) {
+      if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
+        e.preventDefault();
+        if (isOpen) {
+          onClose();
+        }
+      }
+    }
+
+    document.addEventListener('keydown', handleKeydown);
+    return () => document.removeEventListener('keydown', handleKeydown);
+  });
+
+  function handleSearch(value: string) {
+    query = value;
+    selectedIndex = 0;
+
+    if (debounceTimer) clearTimeout(debounceTimer);
+
+    if (!value.trim()) {
+      results = [];
+      isLoading = false;
+      return;
+    }
+
+    isLoading = true;
+    debounceTimer = setTimeout(async () => {
+      try {
+        const response = await fetch(
+          `${baseUrl.replace(/\/$/, '')}/api/search?q=${encodeURIComponent(value.trim())}`
+        );
+        if (response.ok) {
+          const data = await response.json();
+          results = data.results || data || [];
+        } else {
+          results = [];
+        }
+      } catch {
+        results = [];
+      } finally {
+        isLoading = false;
+      }
+    }, 300);
+  }
+
+  function navigateToResult(result: SearchResult) {
+    const version = result.version || config.site?.activeVersion || 'v1';
+    const url = `${baseUrl.replace(/\/$/, '')}/${version}/${result.slug}`;
+    goto(url);
+    onClose();
+  }
+
+  function handleKeydown(e: KeyboardEvent) {
+    switch (e.key) {
+      case 'ArrowDown':
+        e.preventDefault();
+        selectedIndex = Math.min(selectedIndex + 1, results.length - 1);
+        break;
+      case 'ArrowUp':
+        e.preventDefault();
+        selectedIndex = Math.max(selectedIndex - 1, 0);
+        break;
+      case 'Enter':
+        e.preventDefault();
+        if (results[selectedIndex]) {
+          navigateToResult(results[selectedIndex]);
+        }
+        break;
+      case 'Escape':
+        e.preventDefault();
+        onClose();
+        break;
+    }
+  }
+
+  function highlightMatch(text: string, searchQuery: string): string {
+    if (!searchQuery.trim() || !text) return text;
+    const escaped = searchQuery.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const regex = new RegExp(`(${escaped})`, 'gi');
+    return text.replace(regex, '<mark class="bg-primary/20 text-primary rounded-sm px-0.5">$1</mark>');
+  }
+</script>
+
+{#if isOpen}
+  <!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
+  <div
+    class="fixed inset-0 z-50 flex items-start justify-center pt-[15vh]"
+    role="dialog"
+    aria-modal="true"
+    aria-label="Search documentation"
+    onkeydown={handleKeydown}
+  >
+    <!-- Backdrop -->
+    <button
+      class="absolute inset-0 bg-background/80 backdrop-blur-sm"
+      onclick={onClose}
+      aria-label="Close search"
+      tabindex="-1"
+    ></button>
+
+    <!-- Modal -->
+    <div class="relative w-full max-w-lg mx-4 bg-popover border border-border rounded-xl shadow-2xl overflow-hidden">
+      <!-- Search Input -->
+      <div class="flex items-center border-b border-border px-4">
+        <Search class="h-4 w-4 text-muted-foreground shrink-0" />
+        <input
+          bind:this={inputEl}
+          type="text"
+          placeholder={config.search?.placeholder || 'Search documentation...'}
+          value={query}
+          oninput={(e) => handleSearch(e.currentTarget.value)}
+          class="flex-1 h-12 px-3 bg-transparent text-sm text-foreground placeholder:text-muted-foreground outline-none"
+        />
+        {#if isLoading}
+          <Loader2 class="h-4 w-4 text-muted-foreground animate-spin shrink-0" />
+        {:else if query}
+          <button
+            onclick={() => handleSearch('')}
+            class="p-1 hover:bg-accent rounded-md"
+            aria-label="Clear search"
+          >
+            <X class="h-3 w-3 text-muted-foreground" />
+          </button>
+        {/if}
+      </div>
+
+      <!-- Results -->
+      <div class="max-h-80 overflow-y-auto">
+        {#if results.length > 0}
+          <div class="py-2">
+            {#each results as result, index}
+              <button
+                class="w-full flex items-start gap-3 px-4 py-3 text-left transition-colors {index === selectedIndex ? 'bg-accent text-accent-foreground' : 'text-foreground hover:bg-accent/50'}"
+                onclick={() => navigateToResult(result)}
+                onmouseenter={() => (selectedIndex = index)}
+              >
+                <FileText class="h-4 w-4 mt-0.5 text-muted-foreground shrink-0" />
+                <div class="flex-1 min-w-0">
+                  <div class="text-sm font-medium truncate">
+                    {@html highlightMatch(result.title, query)}
+                  </div>
+                  {#if result.description || result.excerpt}
+                    <div class="text-xs text-muted-foreground mt-0.5 line-clamp-2">
+                      {@html highlightMatch(result.description || result.excerpt || '', query)}
+                    </div>
+                  {/if}
+                  {#if result.headings && result.headings.length > 0}
+                    <div class="flex flex-wrap gap-1 mt-1">
+                      {#each result.headings.slice(0, 3) as heading}
+                        <span class="inline-flex items-center gap-0.5 text-xs text-muted-foreground">
+                          <Hash class="h-2.5 w-2.5" />
+                          {heading.title}
+                        </span>
+                      {/each}
+                    </div>
+                  {/if}
+                </div>
+              </button>
+            {/each}
+          </div>
+        {:else if query && !isLoading}
+          <div class="py-12 text-center">
+            <p class="text-sm text-muted-foreground">No results found for "{query}"</p>
+            <p class="text-xs text-muted-foreground mt-1">Try different keywords or check spelling</p>
+          </div>
+        {:else if !query}
+          <div class="py-12 text-center">
+            <p class="text-sm text-muted-foreground">Start typing to search...</p>
+          </div>
+        {/if}
+      </div>
+
+      <!-- Footer -->
+      <div class="flex items-center gap-4 px-4 py-2 border-t border-border text-xs text-muted-foreground">
+        <span class="inline-flex items-center gap-1">
+          <ArrowUp class="h-3 w-3" />
+          <ArrowDown class="h-3 w-3" />
+          navigate
+        </span>
+        <span class="inline-flex items-center gap-1">
+          <CornerDownLeft class="h-3 w-3" />
+          open
+        </span>
+        <span class="inline-flex items-center gap-1">
+          <kbd class="px-1.5 py-0.5 rounded border border-border bg-muted text-[10px] font-mono">esc</kbd>
+          close
+        </span>
+      </div>
+    </div>
+  </div>
+{/if}

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

@@ -0,0 +1,9 @@
+import type { SpecraConfig } from '../../config.types.js';
+interface Props {
+    isOpen: boolean;
+    onClose: () => void;
+    config: SpecraConfig;
+}
+declare const SearchModal: import("svelte").Component<Props, {}, "">;
+type SearchModal = ReturnType<typeof SearchModal>;
+export default SearchModal;

package/dist/components/docs/Sidebar.svelte

@@ -0,0 +1,69 @@
+<script lang="ts">
+  import type { SpecraConfig } from '../../config.types.js';
+  import SidebarMenuItems from './SidebarMenuItems.svelte';
+
+  interface DocItem {
+    title: string;
+    slug: string;
+    filePath: string;
+    section?: string;
+    group?: string;
+    sidebar?: string;
+    sidebar_position?: number;
+    categoryLabel?: string;
+    categoryPosition?: number;
+    categoryCollapsible?: boolean;
+    categoryCollapsed?: boolean;
+    categoryIcon?: string;
+    categoryTabGroup?: string;
+    meta?: {
+      icon?: string;
+      tab_group?: string;
+      [key: string]: any;
+    };
+  }
+
+  interface Props {
+    docs: DocItem[];
+    version: string;
+    onLinkClick?: () => void;
+    config: SpecraConfig;
+    activeTabGroup?: string;
+  }
+
+  let { docs, version, onLinkClick, config, activeTabGroup }: Props = $props();
+
+  let hasTabGroups = $derived(
+    config.navigation?.tabGroups && config.navigation.tabGroups.length > 0
+  );
+  let isFlush = $derived(config.navigation?.sidebarStyle === 'flush');
+  let stickyTop = $derived(hasTabGroups ? 'top-[7.5rem]' : 'top-24');
+  let maxHeight = $derived(
+    hasTabGroups ? 'max-h-[calc(100vh-10rem)]' : 'max-h-[calc(100vh-7rem)]'
+  );
+  let containerClass = $derived(
+    isFlush
+      ? `${maxHeight} overflow-y-auto p-4 border-r border-border`
+      : `${maxHeight} overflow-y-auto bg-muted/30 dark:bg-muted/10 rounded-2xl p-4 border border-border/50`
+  );
+</script>
+
+{#if config.navigation?.showSidebar}
+  <aside class="w-64 shrink-0 sticky {stickyTop} self-start">
+    <div class={containerClass}>
+      <div class="flex items-center justify-between mb-4 px-2">
+        <h2 class="text-xs font-semibold text-muted-foreground uppercase tracking-wider">Documentation</h2>
+        {#if config.features?.showVersionBadge && version}
+          <span class="text-xs font-medium text-muted-foreground bg-muted px-2 py-0.5 rounded-md">{version}</span>
+        {/if}
+      </div>
+      <SidebarMenuItems
+        {docs}
+        {version}
+        {onLinkClick}
+        {config}
+        {activeTabGroup}
+      />
+    </div>
+  </aside>
+{/if}

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

@@ -0,0 +1,31 @@
+import type { SpecraConfig } from '../../config.types.js';
+interface DocItem {
+    title: string;
+    slug: string;
+    filePath: string;
+    section?: string;
+    group?: string;
+    sidebar?: string;
+    sidebar_position?: number;
+    categoryLabel?: string;
+    categoryPosition?: number;
+    categoryCollapsible?: boolean;
+    categoryCollapsed?: boolean;
+    categoryIcon?: string;
+    categoryTabGroup?: string;
+    meta?: {
+        icon?: string;
+        tab_group?: string;
+        [key: string]: any;
+    };
+}
+interface Props {
+    docs: DocItem[];
+    version: string;
+    onLinkClick?: () => void;
+    config: SpecraConfig;
+    activeTabGroup?: string;
+}
+declare const Sidebar: import("svelte").Component<Props, {}, "">;
+type Sidebar = ReturnType<typeof Sidebar>;
+export default Sidebar;