@alliance-droid/svelte-docs-system 0.0.1

package/src/lib/components/Image.svelte

@@ -0,0 +1,100 @@
+<script lang="ts">
+  /**
+   * Image component with caption support
+   * Provides responsive images with optional captions and alt text
+   */
+
+  interface Props {
+    src: string;
+    alt: string;
+    caption?: string;
+    width?: number;
+    height?: number;
+    zoomable?: boolean;
+  }
+
+  let { src, alt, caption, width, height, zoomable = true }: Props = $props();
+
+  let isZoomed = $state(false);
+
+  function handleZoom() {
+    if (zoomable) {
+      isZoomed = !isZoomed;
+    }
+  }
+
+  function handleKeydown(e: KeyboardEvent) {
+    if (e.key === 'Escape' && isZoomed) {
+      isZoomed = false;
+    }
+  }
+</script>
+
+<svelte:window on:keydown={handleKeydown} />
+
+<figure class="my-6 flex flex-col items-center gap-2">
+  <div class="relative w-full max-w-4xl overflow-hidden rounded-lg border border-gray-200 dark:border-gray-700">
+    <!-- Zoomed overlay -->
+    {#if isZoomed}
+      <div
+        class="fixed inset-0 z-50 flex cursor-pointer items-center justify-center bg-black/80 backdrop-blur"
+        onclick={() => (isZoomed = false)}
+        onkeydown={(e) => {
+          if (e.key === 'Enter' || e.key === ' ') {
+            isZoomed = false;
+          }
+        }}
+        role="button"
+        tabindex="0"
+      >
+        <img
+          {src}
+          {alt}
+          class="max-h-[90vh] max-w-[90vw] rounded-lg object-contain"
+          {width}
+          {height}
+        />
+      </div>
+    {/if}
+
+    <!-- Regular image wrapper for clickability -->
+    <button
+      onclick={handleZoom}
+      class="w-full border-0 bg-transparent p-0"
+      aria-label={zoomable ? 'Click to zoom image' : ''}
+      type="button"
+    >
+      <img
+        {src}
+        {alt}
+        {width}
+        {height}
+        class="w-full object-cover {zoomable ? 'cursor-zoom-in hover:opacity-90' : ''} transition-opacity"
+      />
+    </button>
+  </div>
+
+  {#if caption}
+    <figcaption class="text-center text-sm text-gray-600 dark:text-gray-400">
+      {caption}
+    </figcaption>
+  {/if}
+</figure>
+
+<style>
+  figure {
+    margin-top: 1.5rem;
+    margin-bottom: 1.5rem;
+  }
+
+  figcaption {
+    margin-top: 0.5rem;
+    text-align: center;
+    font-size: 0.875rem;
+    color: #4b5563;
+  }
+
+  :global(.dark) figcaption {
+    color: #9ca3af;
+  }
+</style>

package/src/lib/components/Image.test.ts

@@ -0,0 +1,163 @@
+import { describe, it, expect } from 'vitest';
+
+/**
+ * Unit tests for Image component
+ * Tests image rendering, optimization, and accessibility
+ */
+
+describe('Image Component', () => {
+  describe('Image Props', () => {
+    it('should require src attribute', () => {
+      const src = '/images/example.png';
+      expect(src).toBeDefined();
+      expect(typeof src).toBe('string');
+      expect(src.startsWith('/')).toBe(true);
+    });
+
+    it('should require alt text for accessibility', () => {
+      const alt = 'A description of the image';
+      expect(alt).toBeDefined();
+      expect(typeof alt).toBe('string');
+      expect(alt.length).toBeGreaterThan(0);
+    });
+
+    it('should accept various image formats', () => {
+      const formats = ['.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg'];
+      const validSrc = 'image.webp';
+      expect(formats.some((fmt) => validSrc.endsWith(fmt))).toBe(true);
+    });
+
+    it('should accept optional width and height', () => {
+      const width = 800;
+      const height = 600;
+      expect(typeof width).toBe('number');
+      expect(typeof height).toBe('number');
+      expect(width).toBeGreaterThan(0);
+      expect(height).toBeGreaterThan(0);
+    });
+
+    it('should accept optional caption', () => {
+      const caption = 'Figure 1: Example screenshot';
+      expect(typeof caption).toBe('string');
+    });
+  });
+
+  describe('Image Optimization', () => {
+    it('should support responsive images with srcset', () => {
+      const srcset =
+        '/img/small.webp 640w, /img/medium.webp 1024w, /img/large.webp 1920w';
+      expect(srcset).toContain('640w');
+      expect(srcset).toContain('1024w');
+      expect(srcset).toContain('1920w');
+    });
+
+    it('should support multiple image formats with picture element', () => {
+      const formats = ['webp', 'jpg', 'png'];
+      formats.forEach((fmt) => {
+        expect(['webp', 'jpg', 'png']).toContain(fmt);
+      });
+    });
+
+    it('should lazy load images by default', () => {
+      const loading = 'lazy';
+      expect(['lazy', 'eager']).toContain(loading);
+    });
+
+    it('should support eager loading when needed', () => {
+      const loading = 'eager';
+      expect(['lazy', 'eager']).toContain(loading);
+    });
+  });
+
+  describe('Responsive Behavior', () => {
+    it('should support CSS aspect ratio', () => {
+      const aspectRatio = '16/9';
+      expect(aspectRatio).toContain('/');
+    });
+
+    it('should preserve aspect ratio', () => {
+      const width = 800;
+      const height = 600;
+      const aspectRatio = width / height;
+      expect(aspectRatio).toBeCloseTo(1.33, 1);
+    });
+
+    it('should scale to container width', () => {
+      const maxWidth = '100%';
+      expect(maxWidth).toBe('100%');
+    });
+  });
+
+  describe('Figure and Caption', () => {
+    it('should wrap in figure element', () => {
+      const element = 'figure';
+      expect(element).toBe('figure');
+    });
+
+    it('should support caption with figcaption', () => {
+      const caption = 'Example figure caption';
+      expect(caption).toBeTruthy();
+    });
+
+    it('should associate caption with image', () => {
+      const figcaptionId = 'img-caption-1';
+      const ariaDescribedBy = 'img-caption-1';
+      expect(ariaDescribedBy).toBe(figcaptionId);
+    });
+  });
+
+  describe('Accessibility', () => {
+    it('should have descriptive alt text', () => {
+      const alt = 'A screenshot showing the dashboard with user metrics';
+      expect(alt.length).toBeGreaterThan(10);
+    });
+
+    it('should not have empty alt text', () => {
+      const alt = 'Important diagram';
+      expect(alt.length).toBeGreaterThan(0);
+    });
+
+    it('should avoid decorative image alt text', () => {
+      const decorativeAlt = 'spacer';
+      const meaningfulAlt = 'Navigation menu icon';
+      expect(meaningfulAlt.length).toBeGreaterThan(decorativeAlt.length);
+    });
+
+    it('should have proper figure structure', () => {
+      const figureElement = 'figure';
+      const figcaptionElement = 'figcaption';
+      expect(figureElement).toBeDefined();
+      expect(figcaptionElement).toBeDefined();
+    });
+
+    it('should support extended descriptions for complex images', () => {
+      const longdesc = '/docs/image-description.html';
+      expect(longdesc).toBeTruthy();
+    });
+  });
+
+  describe('Dark Mode Support', () => {
+    it('should support dark mode styling', () => {
+      const lightClass = 'border-gray-200';
+      const darkClass = 'dark:border-gray-700';
+      expect(darkClass).toContain('dark:');
+    });
+
+    it('should maintain contrast in dark mode', () => {
+      const darkModeEnabled = true;
+      expect(darkModeEnabled).toBe(true);
+    });
+  });
+
+  describe('Browser Support', () => {
+    it('should provide fallback for old browsers', () => {
+      const hasFallback = true;
+      expect(hasFallback).toBe(true);
+    });
+
+    it('should support webp with fallback', () => {
+      const hasPicture = true;
+      expect(hasPicture).toBe(true);
+    });
+  });
+});

package/src/lib/components/Navbar.svelte

@@ -0,0 +1,141 @@
+<script lang="ts">
+  import { theme } from '$lib/stores/theme';
+  import { sidebarOpen } from '$lib/stores/nav';
+  import { version } from '$lib/stores/version';
+  import { i18n } from '$lib/stores/i18n';
+  import { onMount } from 'svelte';
+
+  let { 
+    title = 'Docs',
+    logo = null,
+    onLogoClick = () => {},
+    onVersionChange = (ver: string) => {},
+    onLanguageChange = (lang: string) => {},
+  }: {
+    title?: string;
+    logo?: string | null;
+    onLogoClick?: () => void;
+    onVersionChange?: (version: string) => void;
+    onLanguageChange?: (language: string) => void;
+  } = $props();
+
+  let isDark = $derived($theme === 'dark');
+  let currentVersion = $derived.by(() => $version.current);
+  let currentLanguage = $derived.by(() => $i18n.currentLanguage);
+  let availableVersions = $derived.by(() => $version.availableVersions);
+  let availableLanguages = $derived.by(() => $i18n.availableLanguages);
+  let isMounted = $state(false);
+
+  onMount(() => {
+    isMounted = true;
+  });
+
+  function toggleTheme() {
+    theme.toggle();
+  }
+
+  function toggleSidebar() {
+    sidebarOpen.update(v => !v);
+  }
+
+  function handleVersionChange(e: Event) {
+    const select = e.target as HTMLSelectElement;
+    const newVersion = select.value;
+    version.setVersion(newVersion);
+    onVersionChange(newVersion);
+  }
+
+  function handleLanguageChange(e: Event) {
+    const select = e.target as HTMLSelectElement;
+    const newLanguage = select.value;
+    i18n.setLanguage(newLanguage as any);
+    onLanguageChange(newLanguage);
+  }
+</script>
+
+<nav class="sticky top-0 z-40 border-b border-claude-border dark:border-claude-dark-border bg-white dark:bg-claude-dark-bg-secondary backdrop-blur-sm">
+  <div class="doc-container flex items-center justify-between h-16 px-4 sm:px-6">
+    <!-- Logo / Brand -->
+    <button
+      onclick={onLogoClick}
+      class="flex items-center gap-2 font-semibold text-lg text-claude-text dark:text-claude-dark-text hover:text-claude-accent dark:hover:text-claude-dark-accent transition-colors"
+      aria-label="Home"
+    >
+      {#if logo}
+        <img src={logo} alt="Logo" class="h-8 w-8" />
+      {/if}
+      <span>{title}</span>
+    </button>
+
+    <!-- Mobile Menu Button -->
+    <button
+      onclick={toggleSidebar}
+      class="md:hidden p-2 hover:bg-claude-bg-secondary dark:hover:bg-claude-dark-bg rounded-lg transition-colors"
+      aria-label="Toggle menu"
+    >
+      <svg class="w-6 h-6" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 6h16M4 12h16M4 18h16" />
+      </svg>
+    </button>
+
+    <!-- Right Section: Language, Version, Theme Toggle -->
+    <div class="hidden md:flex items-center gap-4">
+      <!-- Language Switcher -->
+      {#if isMounted && availableLanguages.length > 0}
+        <select
+          value={currentLanguage}
+          onchange={handleLanguageChange}
+          class="px-3 py-2 rounded-lg bg-claude-bg-secondary dark:bg-claude-dark-bg border border-claude-border dark:border-claude-dark-border text-claude-text dark:text-claude-dark-text text-sm cursor-pointer hover:border-claude-accent dark:hover:border-claude-dark-accent transition-colors"
+          aria-label="Select language"
+        >
+          {#each availableLanguages as lang (lang.code)}
+            <option value={lang.code}>
+              {lang.label}
+            </option>
+          {/each}
+        </select>
+      {/if}
+
+      <!-- Version Switcher -->
+      {#if isMounted && availableVersions.length > 0}
+        <select
+          value={currentVersion}
+          onchange={handleVersionChange}
+          class="px-3 py-2 rounded-lg bg-claude-bg-secondary dark:bg-claude-dark-bg border border-claude-border dark:border-claude-dark-border text-claude-text dark:text-claude-dark-text text-sm cursor-pointer hover:border-claude-accent dark:hover:border-claude-dark-accent transition-colors"
+          aria-label="Select version"
+        >
+          {#each availableVersions as ver (ver.version)}
+            <option value={ver.version}>
+              {ver.label}
+            </option>
+          {/each}
+        </select>
+      {/if}
+
+      <!-- Dark Mode Toggle -->
+      <button
+        onclick={toggleTheme}
+        class="p-2 rounded-lg bg-claude-bg-secondary dark:bg-claude-dark-bg border border-claude-border dark:border-claude-dark-border hover:border-claude-accent dark:hover:border-claude-dark-accent transition-colors"
+        aria-label="Toggle dark mode"
+      >
+        {#if isDark}
+          <!-- Moon Icon -->
+          <svg class="w-5 h-5 text-claude-accent dark:text-claude-dark-accent" fill="currentColor" viewBox="0 0 20 20">
+            <path d="M17.293 13.293A8 8 0 016.707 2.707a8.001 8.001 0 1010.586 10.586z" />
+          </svg>
+        {:else}
+          <!-- Sun Icon -->
+          <svg class="w-5 h-5 text-claude-accent" fill="currentColor" viewBox="0 0 20 20">
+            <path fill-rule="evenodd" d="M10 2a1 1 0 011 1v1a1 1 0 11-2 0V3a1 1 0 011-1zm4.323 2.323a1 1 0 011.414 0l.707.707a1 1 0 11-1.414 1.414l-.707-.707a1 1 0 010-1.414zm2.828 2.828a1 1 0 011.414 0l.707.707a1 1 0 11-1.414 1.414l-.707-.707a1 1 0 010-1.414zm2.828 2.828a1 1 0 011.414 0l.707.707a1 1 0 11-1.414 1.414l-.707-.707a1 1 0 010-1.414zM10 11a1 1 0 110 2 1 1 0 010-2zm4.464-1.465a1 1 0 111.414-1.414l.707.707a1 1 0 11-1.414 1.414l-.707-.707zm2.828 2.828a1 1 0 111.414-1.414l.707.707a1 1 0 11-1.414 1.414l-.707-.707zm2.828 2.828a1 1 0 111.414-1.414l.707.707a1 1 0 11-1.414 1.414l-.707-.707zM10 18a1 1 0 110-2 1 1 0 010 2zm-4.464-1.465a1 1 0 11-1.414-1.414l.707-.707a1 1 0 011.414 1.414l-.707.707zm-2.828-2.828a1 1 0 11-1.414-1.414l.707-.707a1 1 0 011.414 1.414l-.707.707zm-2.828-2.828a1 1 0 11-1.414-1.414l.707-.707a1 1 0 011.414 1.414l-.707.707z" clip-rule="evenodd" />
+          </svg>
+        {/if}
+      </button>
+    </div>
+  </div>
+</nav>
+
+<style>
+  :global(html.dark nav) {
+    background-color: #0f0f0f;
+  }
+</style>

package/src/lib/components/Search.svelte

@@ -0,0 +1,248 @@
+<script lang="ts">
+	import { onMount } from 'svelte';
+	import {
+		query,
+		results,
+		loading,
+		resultCount,
+		initPagefind,
+		updateSearch,
+		clearSearch
+	} from '$lib/stores/search';
+	import { highlightSearchTerms, extractExcerpt } from '$lib/utils/highlight';
+
+	interface Props {
+		showResults?: boolean;
+	}
+
+	let { showResults = true }: Props = $props();
+
+	let searchInput: HTMLInputElement | undefined;
+	let isInitialized = $state(false);
+	let searchError = $state<string | null>(null);
+	let isDropdownOpen = $state(false);
+
+	onMount(async () => {
+		try {
+			await initPagefind();
+			isInitialized = true;
+		} catch (error) {
+			console.error('Failed to initialize search:', error);
+			searchError = 'Failed to initialize search';
+		}
+	});
+
+	async function handleSearch(e: Event) {
+		const target = e.target as HTMLInputElement;
+		const searchQuery = target.value;
+
+		try {
+			searchError = null;
+			await updateSearch(searchQuery);
+		} catch (error) {
+			console.error('Search error:', error);
+			searchError = 'Search failed. Please try again.';
+		}
+	}
+
+	function handleClear() {
+		clearSearch();
+		if (searchInput) {
+			searchInput.focus();
+		}
+	}
+
+	function handleKeyDown(e: KeyboardEvent) {
+		if (e.key === 'Escape') {
+			handleClear();
+			isDropdownOpen = false;
+		}
+	}
+
+	function handleFocus() {
+		isDropdownOpen = true;
+	}
+
+	function handleBlur(e: FocusEvent) {
+		// Only close dropdown if focus moves outside the search container
+		const target = e.relatedTarget as HTMLElement;
+		if (!target || !target.closest('[data-search-container]')) {
+			setTimeout(() => {
+				isDropdownOpen = false;
+			}, 100);
+		}
+	}
+</script>
+
+<div class="relative w-full" data-search-container>
+	<!-- Search Input -->
+	<div class="relative">
+		<input
+			bind:this={searchInput}
+			type="text"
+			placeholder="Search documentation..."
+			value={$query}
+			oninput={handleSearch}
+			onkeydown={handleKeyDown}
+			onfocus={handleFocus}
+			onblur={handleBlur}
+			disabled={!isInitialized}
+			class="w-full rounded-lg border border-gray-300 bg-white px-4 py-2 pl-10 text-sm text-gray-900 placeholder-gray-500 focus:border-blue-500 focus:ring-1 focus:ring-blue-500 dark:border-gray-600 dark:bg-gray-800 dark:text-gray-100 dark:placeholder-gray-400 disabled:opacity-50 transition-all"
+			aria-label="Search documentation"
+		/>
+
+		<!-- Search Icon -->
+		<div class="pointer-events-none absolute inset-y-0 left-0 flex items-center pl-3">
+			{#if $loading}
+				<svg
+					class="h-4 w-4 animate-spin text-gray-400"
+					xmlns="http://www.w3.org/2000/svg"
+					fill="none"
+					viewBox="0 0 24 24"
+				>
+					<circle
+						class="opacity-25"
+						cx="12"
+						cy="12"
+						r="10"
+						stroke="currentColor"
+						stroke-width="4"
+					></circle>
+					<path
+						class="opacity-75"
+						fill="currentColor"
+						d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
+					></path>
+				</svg>
+			{:else}
+				<svg
+					class="h-4 w-4 text-gray-400"
+					xmlns="http://www.w3.org/2000/svg"
+					fill="none"
+					viewBox="0 0 24 24"
+					stroke="currentColor"
+				>
+					<path
+						stroke-linecap="round"
+						stroke-linejoin="round"
+						stroke-width="2"
+						d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z"
+					/>
+				</svg>
+			{/if}
+		</div>
+
+		<!-- Clear Button -->
+		{#if $query}
+			<button
+				onclick={handleClear}
+				class="absolute inset-y-0 right-0 pr-3 text-gray-400 hover:text-gray-600 dark:hover:text-gray-300"
+				aria-label="Clear search"
+			>
+				<svg class="h-4 w-4" fill="currentColor" viewBox="0 0 20 20">
+					<path
+						fill-rule="evenodd"
+						d="M4.293 4.293a1 1 0 011.414 0L10 8.586l4.293-4.293a1 1 0 111.414 1.414L11.414 10l4.293 4.293a1 1 0 01-1.414 1.414L10 11.414l-4.293 4.293a1 1 0 01-1.414-1.414L8.586 10 4.293 5.707a1 1 0 010-1.414z"
+						clip-rule="evenodd"
+					/>
+				</svg>
+			</button>
+		{/if}
+	</div>
+
+	<!-- Error Message -->
+	{#if searchError}
+		<div class="mt-2 rounded-lg bg-red-50 p-3 text-sm text-red-700 dark:bg-red-900/20 dark:text-red-400">
+			{searchError}
+		</div>
+	{/if}
+
+	<!-- Search Results -->
+	{#if showResults && isDropdownOpen && ($query || $results.length > 0)}
+		<div class="absolute top-full left-0 right-0 mt-2 max-h-96 overflow-y-auto rounded-lg border border-gray-300 bg-white shadow-lg dark:border-gray-600 dark:bg-gray-800 z-50">
+			{#if $loading}
+				<div class="px-4 py-8 text-center text-gray-500 dark:text-gray-400">
+					<div class="inline-block">
+						<svg
+							class="h-5 w-5 animate-spin"
+							xmlns="http://www.w3.org/2000/svg"
+							fill="none"
+							viewBox="0 0 24 24"
+						>
+							<circle
+								class="opacity-25"
+								cx="12"
+								cy="12"
+								r="10"
+								stroke="currentColor"
+								stroke-width="4"
+							></circle>
+							<path
+								class="opacity-75"
+								fill="currentColor"
+								d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
+							></path>
+						</svg>
+					</div>
+				</div>
+			{:else if $results.length === 0 && $query}
+				<div class="px-4 py-8 text-center text-gray-500 dark:text-gray-400">
+					No results found for "<strong>{$query}</strong>"
+				</div>
+			{:else if $results.length > 0}
+				<div class="divide-y divide-gray-200 dark:divide-gray-700">
+					{#each $results as result (result.id)}
+						<a
+							href={result.url}
+							class="block px-4 py-3 hover:bg-gray-50 dark:hover:bg-gray-700 transition-colors"
+						>
+							<div class="font-semibold text-gray-900 dark:text-gray-100">
+								{@html highlightSearchTerms(result.title, $query)}
+							</div>
+							{#if result.excerpt || result.content}
+								<div class="mt-1 text-sm text-gray-600 dark:text-gray-400 line-clamp-2">
+									{@html highlightSearchTerms(
+										extractExcerpt(result.content || result.excerpt || '', $query, 200),
+										$query
+									)}
+								</div>
+							{/if}
+							<div class="mt-2 text-xs text-gray-500 dark:text-gray-500">
+								{result.url}
+							</div>
+						</a>
+					{/each}
+				</div>
+
+				{#if $resultCount > 0}
+					<div class="border-t border-gray-200 bg-gray-50 px-4 py-2 text-xs text-gray-600 dark:border-gray-700 dark:bg-gray-700/50 dark:text-gray-400">
+						{$resultCount} result{$resultCount !== 1 ? 's' : ''} found
+					</div>
+				{/if}
+			{/if}
+		</div>
+	{/if}
+</div>
+
+<style>
+	:global(.line-clamp-2) {
+		display: -webkit-box;
+		-webkit-line-clamp: 2;
+		-webkit-box-orient: vertical;
+		line-clamp: 2;
+		overflow: hidden;
+	}
+
+	:global(mark) {
+		background-color: #fef3c7;
+		color: #92400e;
+		font-weight: 500;
+		padding: 0 0.125rem;
+		border-radius: 0.125rem;
+	}
+
+	:global(.dark mark) {
+		background-color: #78350f;
+		color: #fef3c7;
+	}
+</style>