specra 0.1.13 → 0.2.0

package/dist/components/docs/Image.svelte

@@ -0,0 +1,88 @@
+<script lang="ts">
+  import { ZoomIn, X } from 'lucide-svelte';
+
+  interface Props {
+    src: string;
+    alt: string;
+    caption?: string;
+    width?: number;
+    height?: number;
+    zoom?: boolean;
+  }
+
+  let {
+    src,
+    alt,
+    caption,
+    width,
+    height,
+    zoom = true,
+  }: Props = $props();
+
+  let isZoomed = $state(false);
+
+  function handleKeydown(event: KeyboardEvent) {
+    if (event.key === 'Escape' && isZoomed) {
+      isZoomed = false;
+    }
+  }
+</script>
+
+<svelte:window onkeydown={handleKeydown} />
+
+<figure class="my-6">
+  <div class="relative group rounded-xl border border-border overflow-hidden bg-muted/30">
+    <img
+      {src}
+      {alt}
+      width={width || 1200}
+      height={height || 675}
+      class="w-full h-auto"
+      loading="lazy"
+    />
+    {#if zoom}
+      <button
+        onclick={() => (isZoomed = true)}
+        class="absolute top-3 right-3 p-2 rounded-md bg-background/80 backdrop-blur-sm border border-border opacity-0 group-hover:opacity-100 transition-opacity hover:bg-background"
+        aria-label="Zoom image"
+      >
+        <ZoomIn class="h-4 w-4 text-foreground" />
+      </button>
+    {/if}
+  </div>
+  {#if caption}
+    <figcaption class="mt-2 text-center text-sm text-muted-foreground italic">
+      {caption}
+    </figcaption>
+  {/if}
+</figure>
+
+<!-- Zoom Modal -->
+{#if isZoomed}
+  <!-- svelte-ignore a11y_no_static_element_interactions -->
+  <div
+    class="fixed inset-0 z-50 bg-background/95 backdrop-blur-sm flex items-center justify-center p-4"
+    onclick={() => (isZoomed = false)}
+    onkeydown={(e) => { if (e.key === 'Escape') isZoomed = false; }}
+  >
+    <button
+      onclick={() => (isZoomed = false)}
+      class="absolute top-4 right-4 p-2 rounded-md bg-muted hover:bg-muted/80 transition-colors"
+      aria-label="Close"
+    >
+      <X class="h-5 w-5 text-foreground" />
+    </button>
+    <div class="max-w-7xl max-h-[90vh] overflow-auto">
+      <!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
+      <img
+        {src}
+        {alt}
+        width={width || 1920}
+        height={height || 1080}
+        class="w-full h-auto"
+        onclick={(e) => e.stopPropagation()}
+        onkeydown={(e) => { if (e.key === 'Enter') e.stopPropagation(); }}
+      />
+    </div>
+  </div>
+{/if}

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

@@ -0,0 +1,11 @@
+interface Props {
+    src: string;
+    alt: string;
+    caption?: string;
+    width?: number;
+    height?: number;
+    zoom?: boolean;
+}
+declare const Image: import("svelte").Component<Props, {}, "">;
+type Image = ReturnType<typeof Image>;
+export default Image;

package/dist/components/docs/ImageCard.svelte

@@ -0,0 +1,91 @@
+<script lang="ts">
+  interface Props {
+    src: string;
+    alt: string;
+    title?: string;
+    description?: string;
+    href?: string;
+    external?: boolean;
+    aspectRatio?: 'square' | 'video' | 'portrait';
+  }
+
+  let {
+    src,
+    alt,
+    title,
+    description,
+    href,
+    external = false,
+    aspectRatio = 'video',
+  }: Props = $props();
+
+  const aspectRatios: Record<string, string> = {
+    square: 'aspect-square',
+    video: 'aspect-video',
+    portrait: 'aspect-[3/4]',
+  };
+
+  let aspectClass = $derived(aspectRatios[aspectRatio] || aspectRatios.video);
+  let hasInfo = $derived(!!title || !!description);
+</script>
+
+{#if href}
+  <a
+    {href}
+    class="image-card-link group block rounded-xl border border-border hover:border-primary/50 hover:shadow-lg transition-all overflow-hidden p-0"
+    target={external ? '_blank' : undefined}
+    rel={external ? 'noopener noreferrer' : undefined}
+  >
+    <div class="flex flex-col gap-0 p-0">
+      <div class="w-full {aspectClass} overflow-hidden {hasInfo ? 'rounded-t-xl' : 'rounded-xl'} bg-muted relative">
+        <img
+          {src}
+          {alt}
+          class="object-cover transition-transform duration-300 group-hover:scale-105 absolute inset-0 w-full h-full"
+          loading="lazy"
+        />
+      </div>
+      {#if hasInfo}
+        <div class="p-3 flex flex-col gap-1">
+          {#if title}
+            <h3 class="font-semibold text-foreground mb-0 no-underline group-hover:text-primary transition-colors">
+              {title}
+            </h3>
+          {/if}
+          {#if description}
+            <p class="text-sm text-muted-foreground line-clamp-2 no-underline mb-0">
+              {description}
+            </p>
+          {/if}
+        </div>
+      {/if}
+    </div>
+  </a>
+{:else}
+  <div class="block rounded-xl border border-border overflow-hidden bg-card p-0">
+    <div class="flex flex-col gap-0 p-0">
+      <div class="w-full {aspectClass} overflow-hidden {hasInfo ? 'rounded-t-xl' : 'rounded-xl'} bg-muted relative">
+        <img
+          {src}
+          {alt}
+          class="object-cover absolute inset-0 w-full h-full"
+          loading="lazy"
+        />
+      </div>
+      {#if hasInfo}
+        <div class="p-3 flex flex-col gap-1">
+          {#if title}
+            <h3 class="font-semibold text-foreground mb-0 no-underline">
+              {title}
+            </h3>
+          {/if}
+          {#if description}
+            <p class="text-sm text-muted-foreground line-clamp-2 no-underline mb-0">
+              {description}
+            </p>
+          {/if}
+        </div>
+      {/if}
+    </div>
+  </div>
+{/if}

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

@@ -0,0 +1,12 @@
+interface Props {
+    src: string;
+    alt: string;
+    title?: string;
+    description?: string;
+    href?: string;
+    external?: boolean;
+    aspectRatio?: 'square' | 'video' | 'portrait';
+}
+declare const ImageCard: import("svelte").Component<Props, {}, "">;
+type ImageCard = ReturnType<typeof ImageCard>;
+export default ImageCard;

package/dist/components/docs/ImageCardGrid.svelte

@@ -0,0 +1,25 @@
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+
+  interface Props {
+    cols?: 1 | 2 | 3 | 4;
+    children?: Snippet;
+  }
+
+  let { cols = 3, children }: Props = $props();
+
+  const gridCols: Record<number, string> = {
+    1: 'grid-cols-1',
+    2: 'grid-cols-1 md:grid-cols-2',
+    3: 'grid-cols-1 md:grid-cols-2 lg:grid-cols-3',
+    4: 'grid-cols-1 md:grid-cols-2 lg:grid-cols-4',
+  };
+
+  let gridClass = $derived(gridCols[cols] || gridCols[3]);
+</script>
+
+<div class="grid {gridClass} gap-4 my-6">
+  {#if children}
+    {@render children()}
+  {/if}
+</div>

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

@@ -0,0 +1,8 @@
+import type { Snippet } from 'svelte';
+interface Props {
+    cols?: 1 | 2 | 3 | 4;
+    children?: Snippet;
+}
+declare const ImageCardGrid: import("svelte").Component<Props, {}, "">;
+type ImageCardGrid = ReturnType<typeof ImageCardGrid>;
+export default ImageCardGrid;

package/dist/components/docs/LayoutProviders.svelte

@@ -0,0 +1,57 @@
+<script lang="ts">
+  /**
+   * Root layout provider that initializes all Specra stores.
+   * Use this in your root +layout.svelte to set up config, theme, and tab state.
+   *
+   * In Svelte, this replaces:
+   * - React ConfigProvider
+   * - React TabProvider + TabSync
+   * - React SidebarStateProvider
+   * - React ThemeProvider (next-themes)
+   *
+   * Usage:
+   * ```svelte
+   * <LayoutProviders config={data.config}>
+   *   <slot />
+   * </LayoutProviders>
+   * ```
+   */
+  import { onMount } from 'svelte'
+  import { setConfigContext } from '../../stores/config'
+  import { tabStore } from '../../stores/tabs'
+  import { themeStore } from '../../stores/theme'
+  import type { SpecraConfig } from '../../config.types'
+
+  let {
+    config,
+    currentPageTabGroup,
+    children
+  }: {
+    config: SpecraConfig
+    currentPageTabGroup?: string
+    children?: import('svelte').Snippet
+  } = $props()
+
+  // Set config in context for child components
+  const configCtx = setConfigContext(config)
+
+  // Update config context when prop changes
+  $effect(() => {
+    configCtx.set(config)
+  })
+
+  // Initialize tab store
+  $effect(() => {
+    const defaultTab = config.navigation?.tabGroups?.[0]?.id || ''
+    tabStore.initialize(defaultTab)
+  })
+
+  // Sync tab state when page tab group changes
+  $effect(() => {
+    if (currentPageTabGroup) {
+      tabStore.set(currentPageTabGroup)
+    }
+  })
+</script>
+
+{@render children?.()}

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

@@ -0,0 +1,9 @@
+import type { SpecraConfig } from '../../config.types';
+type $$ComponentProps = {
+    config: SpecraConfig;
+    currentPageTabGroup?: string;
+    children?: import('svelte').Snippet;
+};
+declare const LayoutProviders: import("svelte").Component<$$ComponentProps, {}, "">;
+type LayoutProviders = ReturnType<typeof LayoutProviders>;
+export default LayoutProviders;

package/dist/components/docs/Logo.svelte

@@ -0,0 +1,25 @@
+<script lang="ts">
+  import { themeStore } from '../../stores/theme.js';
+
+  interface Props {
+    logo?: string | { light: string; dark: string };
+    alt?: string;
+    className?: string;
+  }
+
+  let { logo, alt = 'Logo', className = 'h-8 w-8 object-contain' }: Props = $props();
+
+  let currentSrc = $derived.by(() => {
+    if (!logo) return '';
+    if (typeof logo === 'string') return logo;
+    return $themeStore === 'dark' ? logo.dark : logo.light;
+  });
+</script>
+
+{#if logo}
+  <img
+    src={currentSrc}
+    {alt}
+    class={className}
+  />
+{/if}

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

@@ -0,0 +1,11 @@
+interface Props {
+    logo?: string | {
+        light: string;
+        dark: string;
+    };
+    alt?: string;
+    className?: string;
+}
+declare const Logo: import("svelte").Component<Props, {}, "">;
+type Logo = ReturnType<typeof Logo>;
+export default Logo;

package/dist/components/docs/Math.svelte

@@ -0,0 +1,54 @@
+<script lang="ts">
+  import { onMount } from 'svelte';
+
+  interface Props {
+    children: string;
+    block?: boolean;
+  }
+
+  let { children, block = false }: Props = $props();
+
+  let containerEl: HTMLSpanElement | HTMLDivElement;
+
+  async function renderMath(el: HTMLElement, expr: string, displayMode: boolean) {
+    try {
+      const katex = (await import('katex')).default;
+      katex.render(expr, el, {
+        throwOnError: false,
+        displayMode,
+      });
+    } catch (err) {
+      console.error('KaTeX rendering error:', err);
+      if (el) {
+        el.textContent = expr;
+      }
+    }
+  }
+
+  onMount(() => {
+    if (containerEl) {
+      renderMath(containerEl, children, block);
+    }
+  });
+
+  // Re-render when children or block changes
+  $effect(() => {
+    const expr = children;
+    const isBlock = block;
+    if (containerEl) {
+      renderMath(containerEl, expr, isBlock);
+    }
+  });
+</script>
+
+{#if block}
+  <div
+    bind:this={containerEl}
+    class="my-6 overflow-x-auto text-center"
+  ></div>
+{:else}
+  <span
+    bind:this={containerEl}
+    class="inline-block"
+  ></span>
+{/if}

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

@@ -0,0 +1,7 @@
+interface Props {
+    children: string;
+    block?: boolean;
+}
+declare const Math: import("svelte").Component<Props, {}, "">;
+type Math = ReturnType<typeof Math>;
+export default Math;

package/dist/components/docs/MdxContent.svelte

@@ -0,0 +1,41 @@
+<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[];
+  }
+
+  interface Props {
+    nodes: MdxNode[];
+    components: Record<string, Component>;
+  }
+
+  let { nodes, components }: Props = $props();
+</script>
+
+{#each nodes as node}
+  {#if node.type === 'html'}
+    {@html node.content}
+  {:else if node.type === 'component' && node.name}
+    {@const Comp = components[node.name]}
+    {#if Comp}
+      {#if node.children && node.children.length > 0}
+        <svelte:component this={Comp} {...node.props}>
+          <MdxContent nodes={node.children} {components} />
+        </svelte:component>
+      {:else}
+        <svelte:component this={Comp} {...node.props} />
+      {/if}
+    {:else}
+      <!-- Unknown component: {node.name} -->
+      {#if node.children}
+        <MdxContent nodes={node.children} {components} />
+      {/if}
+    {/if}
+  {/if}
+{/each}

package/dist/components/docs/MdxHotReload.svelte

@@ -0,0 +1,78 @@
+<script lang="ts">
+  import { browser } from '$app/environment';
+  import { dev } from '$app/environment';
+  import { invalidateAll } from '$app/navigation';
+
+  interface Props {
+    /** Polling interval in ms for checking content changes */
+    pollInterval?: number;
+    /** Whether to automatically refresh on content change */
+    autoRefresh?: boolean;
+  }
+
+  let { pollInterval = 2000, autoRefresh = true }: Props = $props();
+
+  let lastContentHash = $state('');
+  let isWatching = $state(false);
+
+  $effect(() => {
+    if (!browser || !dev || !autoRefresh) return;
+
+    isWatching = true;
+    let intervalId: ReturnType<typeof setInterval>;
+
+    // Use Vite HMR if available
+    if (import.meta.hot) {
+      // Listen for custom mdx/md file changes via Vite plugin
+      import.meta.hot.on('specra:content-update', (data: { file: string; hash?: string }) => {
+        console.log(`[Specra] Content updated: ${data.file}`);
+        invalidateAll();
+      });
+
+      // Also listen for generic file changes that match doc patterns
+      import.meta.hot.on('vite:beforeUpdate', (payload: { updates: Array<{ path: string }> }) => {
+        const hasDocUpdate = payload.updates?.some(
+          (update) =>
+            update.path.includes('/docs/') ||
+            update.path.endsWith('.md') ||
+            update.path.endsWith('.svx') ||
+            update.path.endsWith('.mdx')
+        );
+        if (hasDocUpdate) {
+          console.log('[Specra] Doc file changed, refreshing...');
+          invalidateAll();
+        }
+      });
+    } else {
+      // Fallback: Poll the mdx-watch API endpoint
+      intervalId = setInterval(async () => {
+        try {
+          const res = await fetch('/api/mdx-watch');
+          if (res.ok) {
+            const data = await res.json();
+            const newHash = data.hash || data.timestamp || '';
+
+            if (lastContentHash && newHash !== lastContentHash) {
+              console.log('[Specra] Content change detected, refreshing...');
+              invalidateAll();
+            }
+            lastContentHash = newHash;
+          }
+        } catch {
+          // Silently ignore polling errors
+        }
+      }, pollInterval);
+    }
+
+    return () => {
+      isWatching = false;
+      if (intervalId) clearInterval(intervalId);
+    };
+  });
+</script>
+
+<!-- MdxHotReload is a side-effect only component, no visible output -->
+{#if dev && isWatching}
+  <!-- Hidden marker for dev tools inspection -->
+  <div data-specra-hot-reload="active" class="hidden"></div>
+{/if}

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

@@ -0,0 +1,9 @@
+interface Props {
+    /** Polling interval in ms for checking content changes */
+    pollInterval?: number;
+    /** Whether to automatically refresh on content change */
+    autoRefresh?: boolean;
+}
+declare const MdxHotReload: import("svelte").Component<Props, {}, "">;
+type MdxHotReload = ReturnType<typeof MdxHotReload>;
+export default MdxHotReload;

package/dist/components/docs/MdxLayout.svelte

@@ -0,0 +1,16 @@
+<script lang="ts">
+  /**
+   * mdsvex layout component for documentation pages.
+   * This provides default styling for all markdown content elements.
+   *
+   * Usage in mdsvex config:
+   * ```js
+   * mdsvex({ layout: 'specra/components/MdxLayout' })
+   * ```
+   */
+  let { children }: { children?: import('svelte').Snippet } = $props()
+</script>
+
+<div class="prose prose-slate dark:prose-invert max-w-none prose-headings:scroll-mt-24 prose-headings:font-semibold prose-h1:text-4xl prose-h2:text-3xl prose-h2:mt-12 prose-h2:mb-4 prose-h3:text-2xl prose-h3:mt-8 prose-h3:mb-3 prose-p:text-base prose-p:leading-7 prose-p:text-muted-foreground prose-p:mb-4 prose-a:font-normal prose-a:transition-all prose-code:text-primary prose-code:bg-muted/50 prose-code:px-1.5 prose-code:py-0.5 prose-code:rounded-md prose-code:text-[13px] prose-code:font-mono prose-code:border prose-code:border-border/50 prose-code:before:content-none prose-code:after:content-none prose-pre:bg-transparent prose-pre:p-0 prose-ul:list-disc prose-ul:list-inside prose-ul:space-y-2 prose-ul:mb-4 prose-ol:list-decimal prose-ol:list-inside prose-ol:space-y-2 prose-ol:mb-4 prose-li:leading-7 prose-li:text-muted-foreground prose-strong:text-foreground prose-strong:font-semibold">
+  {@render children?.()}
+</div>

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

@@ -0,0 +1,6 @@
+type $$ComponentProps = {
+    children?: import('svelte').Snippet;
+};
+declare const MdxLayout: import("svelte").Component<$$ComponentProps, {}, "">;
+type MdxLayout = ReturnType<typeof MdxLayout>;
+export default MdxLayout;

package/dist/components/docs/Mermaid.svelte

@@ -0,0 +1,88 @@
+<script lang="ts">
+  import { onMount, onDestroy } from 'svelte';
+
+  interface Props {
+    chart: string;
+    caption?: string;
+  }
+
+  let { chart, caption }: Props = $props();
+
+  let containerEl: HTMLDivElement;
+  let error = $state<string | null>(null);
+
+  async function renderChart() {
+    if (!containerEl) return;
+
+    try {
+      const mermaid = (await import('mermaid')).default;
+
+      mermaid.initialize({
+        startOnLoad: false,
+        theme: document.documentElement.classList.contains('dark') ? 'dark' : 'default',
+        securityLevel: 'loose',
+        fontFamily: 'inherit',
+      });
+
+      const id = `mermaid-${Math.random().toString(36).substr(2, 9)}`;
+      const { svg } = await mermaid.render(id, chart);
+      containerEl.innerHTML = svg;
+      error = null;
+    } catch (err) {
+      console.error('Mermaid rendering error:', err);
+      error = err instanceof Error ? err.message : 'Failed to render diagram';
+    }
+  }
+
+  let observer: MutationObserver | null = null;
+
+  onMount(() => {
+    renderChart();
+
+    // Re-render on theme change
+    observer = new MutationObserver((mutations) => {
+      mutations.forEach((mutation) => {
+        if (mutation.attributeName === 'class') {
+          renderChart();
+        }
+      });
+    });
+
+    observer.observe(document.documentElement, { attributes: true });
+  });
+
+  onDestroy(() => {
+    if (observer) {
+      observer.disconnect();
+      observer = null;
+    }
+  });
+
+  // Re-render when chart prop changes
+  $effect(() => {
+    const _chart = chart;
+    if (containerEl) {
+      renderChart();
+    }
+  });
+</script>
+
+{#if error}
+  <div class="my-6 p-4 rounded-xl border border-red-500/50 bg-red-500/10">
+    <p class="text-sm text-red-600 dark:text-red-400 font-mono">
+      Mermaid Error: {error}
+    </p>
+  </div>
+{:else}
+  <figure class="my-6">
+    <div
+      bind:this={containerEl}
+      class="flex justify-center items-center p-6 rounded-xl border border-border bg-muted/30 overflow-x-auto"
+    ></div>
+    {#if caption}
+      <figcaption class="mt-2 text-center text-sm text-muted-foreground italic">
+        {caption}
+      </figcaption>
+    {/if}
+  </figure>
+{/if}

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

@@ -0,0 +1,7 @@
+interface Props {
+    chart: string;
+    caption?: string;
+}
+declare const Mermaid: import("svelte").Component<Props, {}, "">;
+type Mermaid = ReturnType<typeof Mermaid>;
+export default Mermaid;